/ Hex Artifact Content
Login

Artifact a7c0d013f1e7658d577f444c19401028bebefb8e:


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 34 20 32 30 30 38 2f  in,v 1.314 2008/
05f0: 30 35 2f 32 30 20 31 35 3a 34 34 3a 33 31 20 64  05/20 15:44:31 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 68 61 73 20 74 68 65 20 0a  ction] has the .
8cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
8cd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8ce0: 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 20  es] feature.**  
8cf0: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 64          disabled
8d00: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
8d10: 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20  ** {F12202} The 
8d20: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
8d30: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44  d_result_codes(D
8d40: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  ,F)] interface w
8d50: 69 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  ill enable.**   
8d60: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
8d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
8d80: 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  or the .**      
8d90: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
8da0: 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74  nnection] D if t
8db0: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a  he F parameter.*
8dc0: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 74 72  *          is tr
8dd0: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
8de0: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
8df0: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
8e00: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
8e10: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
8e20: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
8e30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
8e40: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
8e50: 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F12220}.**.** 
8e60: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
8e70: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
8e80: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
8e90: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
8ea0: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
8eb0: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
8ec0: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
8ed0: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
8ee0: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
8ef0: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
8f00: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
8f10: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
8f20: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
8f30: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
8f40: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
8f50: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
8f60: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
8f70: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
8f80: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
8f90: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
8fa0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
8fb0: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
8fc0: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
8fd0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
8fe0: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
8ff0: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
9000: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
9010: 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65   INSERT into the
9020: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
9030: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
9040: 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20  ection.** shown 
9050: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
9060: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
9070: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73  ccessful inserts
9080: 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
9090: 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64  curred on this d
90a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
90b0: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
90c0: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
90d0: 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20  n INSERT occurs 
90e0: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
90f0: 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64  , then the rowid
9100: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72   of the.** inser
9110: 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 72  ted row is retur
9120: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
9130: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
9140: 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73  he trigger.** is
9150: 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f   running.  But o
9160: 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
9170: 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
9180: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
9190: 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
91a0: 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  e reverts to the
91b0: 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
91c0: 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a  rted before the.
91d0: 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 64  ** trigger fired
91e0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52  ..**.** An INSER
91f0: 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  T that fails due
9200: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
9210: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
9220: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
9230: 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65  l insert and doe
9240: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
9250: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
9260: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
9270: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
9280: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
9290: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
92a0: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
92b0: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
92c0: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
92d0: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
92e0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
92f0: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
9300: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
9310: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
9320: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
9330: 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  E .** encounters
9340: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
9350: 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
9360: 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
9370: 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
9380: 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
9390: 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
93a0: 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
93b0: 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
93c0: 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
93d0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
93e0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
93f0: 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
9400: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
9410: 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a  interface. .**.*
9420: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
9430: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
9440: 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 73  ne, an insert is
9450: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
9460: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
9470: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
9480: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
9490: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e  d back..**.** IN
94a0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
94b0: 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71  {F12221} The [sq
94c0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
94d0: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
94e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
94f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 69  **          rowi
9500: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
9510: 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
9520: 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20  insert done.**  
9530: 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
9540: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
9550: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 68  nection and with
9560: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  in the same.**  
9570: 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20          trigger 
9580: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
9590: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a   if there have.*
95a0: 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20  *          been 
95b0: 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e  no qualifying in
95c0: 73 65 72 74 73 20 6f 6e 20 74 68 61 74 20 63 6f  serts on that co
95d0: 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
95e0: 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {F12223} The [sq
95f0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
9600: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
9610: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ion returns.**  
9620: 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c          same val
9630: 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  ue when called f
9640: 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69  rom the same tri
9650: 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  gger context.** 
9660: 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61           immedia
9670: 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20  tely before and 
9680: 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b  after a ROLLBACK
9690: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
96a0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
96b0: 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
96c0: 65 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20  e thread does a 
96d0: 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68  new insert on th
96e0: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
96f0: 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e     database conn
9700: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
9710: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
9720: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
9730: 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
9740: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
9750: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
9760: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
9770: 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20  rowid,.**       
9780: 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75     then the valu
9790: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
97a0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
97b0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
97c0: 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65  *          unpre
97d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
97e0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
97f0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
9800: 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20  he new.**       
9810: 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72     last insert r
9820: 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  owid..*/.sqlite3
9830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
9840: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
9850: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
9860: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
9870: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
9880: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
9890: 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12240}.**.** Th
98a0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
98b0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
98c0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
98d0: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
98e0: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
98f0: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
9900: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
9910: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
9920: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
9930: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  he connection sp
9940: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
9950: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
9960: 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73   Only.** changes
9970: 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
9980: 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
9990: 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
99a0: 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45  TE, or.** DELETE
99b0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
99c0: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
99d0: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
99e0: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
99f0: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
9a00: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
9a10: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
9a20: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
9a30: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
9a40: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
9a50: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
9a60: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
9a70: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
9a80: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
9a90: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
9aa0: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
9ab0: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
9ac0: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
9ad0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
9ae0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
9af0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
9b00: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
9b10: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
9b20: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
9b30: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
9b40: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
9b50: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
9b60: 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
9b70: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
9b80: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
9b90: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
9ba0: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
9bb0: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
9bc0: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
9bd0: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
9be0: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
9bf0: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
9c00: 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
9c10: 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
9c20: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
9c30: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
9c40: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
9c50: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
9c60: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
9c70: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
9c80: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
9c90: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
9ca0: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
9cb0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
9cc0: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
9cd0: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
9ce0: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
9cf0: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
9d00: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
9d10: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
9d20: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
9d30: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
9d40: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
9d50: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
9d60: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
9d70: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
9d80: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
9d90: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
9da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
9db0: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
9dc0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
9dd0: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
9de0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
9df0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
9e00: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
9e10: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
9e20: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
9e30: 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20   So when called 
9e40: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
9e50: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
9e60: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
9e70: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
9e80: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
9e90: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
9ea0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
9eb0: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
9ec0: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
9ed0: 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69   level..** Withi
9ee0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
9ef0: 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c  trigger, the sql
9f00: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
9f10: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20  nterface.** can 
9f20: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
9f30: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
9f40: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
9f50: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
9f60: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
9f70: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
9f80: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
9f90: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
9fa0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
9fb0: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
9fc0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
9fd0: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
9fe0: 6e 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65  nclude in change
9ff0: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
a000: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
a010: 20 74 68 65 79 20 68 61 76 65 20 74 68 65 69 72   they have their
a020: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
a030: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
a040: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
a050: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
a060: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a  able" without.**
a070: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
a080: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
a090: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
a0a0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
a0b0: 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74  much.** faster t
a0c0: 68 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67  han going throug
a0d0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
a0e0: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
a0f0: 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  ts from the.** t
a100: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
a110: 6f 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  of this optimiza
a120: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
a130: 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54  ons in.** "DELET
a140: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
a150: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
a160: 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  s and will not b
a170: 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20  e counted.** by 
a180: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
a190: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
a1a0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
a1b0: 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  )] functions..**
a1c0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
a1d0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
a1e0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
a1f0: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
a200: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
a210: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
a220: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ead..**.** INVAR
a230: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
a240: 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2241} The [sqlit
a250: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  e3_changes()] fu
a260: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
a270: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
a280: 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61           row cha
a290: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
a2a0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
a2b0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
a2c0: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45  *          or DE
a2d0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f  LETE statement o
a2e0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
a2f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
a300: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
a310: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
a320: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
a330: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
a340: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
a350: 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
a360: 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
a370: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  anges..**.** LIM
a380: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
a390: 7b 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {U12252} If a se
a3a0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
a3b0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
a3c0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
a3d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
a3e0: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
a3f0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a400: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
a410: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
a420: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
a430: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
a440: 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66  e and unmeaningf
a450: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
a460: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
a470: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
a480: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
a490: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
a4a0: 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a  fied {F12260}.**
a4b0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
a4c0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
a4d0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
a4e0: 6e 67 65 73 20 63 61 75 73 65 64 0a 2a 2a 20 62  nges caused.** b
a4f0: 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  y INSERT, UPDATE
a500: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
a510: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
a520: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a  database handle.
a530: 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 20  ** was opened.  
a540: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
a550: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
a560: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 0a  rom all trigger.
a570: 2a 2a 20 63 6f 6e 74 65 78 74 73 2e 20 20 42 75  ** contexts.  Bu
a580: 74 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  t the count does
a590: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
a5a0: 6e 67 65 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  nges used to.** 
a5b0: 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43  implement REPLAC
a5c0: 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 64  E constraints, d
a5d0: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
a5e0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
a5f0: 0a 2a 2a 20 6f 72 20 44 52 4f 50 20 74 61 62 6c  .** or DROP tabl
a600: 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a  e processing..**
a610: 20 54 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   The changes.** 
a620: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
a630: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
a640: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
a650: 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
a660: 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74 68 65 20  d .** (when the 
a670: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
a680: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
a690: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
a6a0: 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  or .** [sqlite3_
a6b0: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
a6c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
a6d0: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
a6e0: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
a6f0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a  able" without.**
a700: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
a710: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
a720: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
a730: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
a740: 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74  much.** faster t
a750: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
a760: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
a770: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
a780: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
a790: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
a7a0: 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d  of.** this optim
a7b0: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61  ization, the cha
a7c0: 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44  nge count for "D
a7d0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
a7e0: 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72  " will be.** zer
a7f0: 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  o regardless of 
a800: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
a810: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
a820: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
a830: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20  he.** table. To 
a840: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
a850: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
a860: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
a870: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
a880: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
a890: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
a8a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
a8b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
a8c0: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
a8d0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
a8e0: 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32  NTS:.** .** {F12
a8f0: 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  261} The [sqlite
a900: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
a910: 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  )] returns the t
a920: 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20  otal number.**  
a930: 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63          of row c
a940: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
a950: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
a960: 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a   and/or DELETE.*
a970: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
a980: 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d  ments on the sam
a990: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
a9a0: 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a  ection], in any.
a9b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
a9c0: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e  ger context, sin
a9d0: 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
a9e0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a  connection was.*
a9f0: 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
aa00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
aa10: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
aa20: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
aa30: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
aa40: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
aa50: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
aa60: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
aa70: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
aa80: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
aa90: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
aaa0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a  then the value .
aab0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
aac0: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
aad0: 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e  table and unmean
aae0: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
aaf0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
ab00: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
ab10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ab20: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
ab30: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
ab40: 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12270}.**.** T
ab50: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
ab60: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
ab70: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
ab80: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
ab90: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
aba0: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
abb0: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
abc0: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
abd0: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
abe0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
abf0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
ac00: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
ac10: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
ac20: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
ac30: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
ac40: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
ac50: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
ac60: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
ac70: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
ac80: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
ac90: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
aca0: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
acb0: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
acc0: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
acd0: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
ace0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
acf0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
ad00: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
ad10: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
ad30: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
ad40: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
ad50: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
ad60: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
ad70: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
ad80: 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  L is very nearly
ad90: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
ada0: 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74   time when sqlit
adb0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a  e3_interrupt().*
adc0: 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  * is called, the
add0: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ade0: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
adf0: 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ty to be interru
ae00: 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68  pted..** It migh
ae10: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ae20: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20  mpletion..** An 
ae30: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
ae40: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
ae50: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  d will return.**
ae60: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ae70: 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74  PT].  If the int
ae80: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
ae90: 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20  ration is an.** 
aea0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
aeb0: 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69  or DELETE that i
aec0: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
aed0: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
aee0: 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65  , .** then the e
aef0: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
af00: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
af10: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
af20: 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  lly..** A call t
af30: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
af40: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
af50: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
af60: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
af70: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
af80: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
af90: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
afa0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
afb0: 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68  *.** {F12271} Th
afc0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
afd0: 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
afe0: 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
aff0: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
b000: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
b010: 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
b020: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
b030: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b040: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
b050: 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
b060: 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
b070: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
b080: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
b090: 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  data..**.** {F12
b0a0: 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61  272} Any SQL sta
b0b0: 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69  tement that is i
b0c0: 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73  nterrupted by [s
b0d0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
b0e0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
b0f0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
b100: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
b110: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
b120: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39  S:.**.** {U12279
b130: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
b140: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
b150: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
b160: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
b170: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72  **          is r
b180: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
b190: 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
b1a0: 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
b1b0: 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
b1c0: 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
b1d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b1e0: 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
b1f0: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
b200: 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35  s Complete {F105
b210: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
b220: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
b230: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
b240: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
b250: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
b260: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
b270: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
b280: 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
b290: 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
b2a0: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
b2b0: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
b2c0: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
b2d0: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
b2e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
b2f0: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
b300: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
b310: 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
b320: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
b330: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
b340: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
b350: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
b360: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
b370: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
b380: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
b390: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
b3a0: 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
b3b0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
b3c0: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
b3d0: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
b3e0: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
b3f0: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
b400: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
b410: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
b420: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
b430: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
b440: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
b450: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
b460: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
b470: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
b480: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
b490: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
b4a0: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
b4b0: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
b4c0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
b4d0: 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
b4e0: 20 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20   the SQL and.** 
b4f0: 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  so will not dete
b500: 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
b510: 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
b520: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
b530: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d  :.**.** {F10511}
b540: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
b550: 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69  plete() and sqli
b560: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
b570: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20   functions.**   
b580: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 72         return tr
b590: 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
b5a0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
b5b0: 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20   last.**        
b5c0: 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65    non-whitespace
b5d0: 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20   token in their 
b5e0: 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63  input is a semic
b5f0: 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20  olon that.**    
b600: 20 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20        is not in 
b610: 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49  between the BEGI
b620: 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43  N and END of a C
b630: 52 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a  REATE TRIGGER.**
b640: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
b650: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
b660: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
b670: 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74  10512} The input
b680: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
b690: 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 61  lete() must be a
b6a0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b6b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
b6c0: 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
b6d0: 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e   {U10513} The in
b6e0: 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  put to sqlite3_c
b6f0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74  omplete16() must
b700: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
b710: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
b720: 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
b730: 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
b740: 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
b750: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
b760: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
b770: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
b780: 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
b790: 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
b7a0: 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
b7b0: 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
b7c0: 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
b7d0: 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33  USY Errors {F123
b7e0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
b7f0: 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65  outine identifie
b800: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
b810: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
b820: 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77   be.** invoked w
b830: 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d  henever an attem
b840: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
b850: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
b860: 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f  ble .** that ano
b870: 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70  ther thread or p
b880: 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
b890: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  d..** If the bus
b8a0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
b8b0: 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
b8c0: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
b8d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
b8e0: 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
b8f0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
b900: 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
b910: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66   the lock..** If
b920: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
b930: 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ck is not NULL, 
b940: 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  then the.** call
b950: 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
b960: 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
b970: 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a  guments.  The.**
b980: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
b990: 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  to the handler i
b9a0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
b9b0: 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
b9c0: 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
b9d0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
b9e0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54  this routine.  T
b9f0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ba00: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
ba10: 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  dler is the numb
ba20: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
ba30: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
ba40: 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
ba50: 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
ba60: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20  ocking event.   
ba70: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
ba80: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
ba90: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
baa0: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
bab0: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
bac0: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
bad0: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
bae0: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
baf0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
bb00: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
bb10: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
bb20: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
bb30: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
bb40: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
bb50: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
bb60: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
bb70: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
bb80: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
bb90: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
bba0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
bbb0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
bbc0: 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20  that.** it will 
bbd0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
bbe0: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
bbf0: 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20  ntention..** If 
bc00: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
bc10: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
bc20: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
bc30: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
bc40: 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20  .** a deadlock, 
bc50: 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
bc60: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
bc70: 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20  ITE_BUSY] or.** 
bc80: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
bc90: 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
bca0: 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a  f invoking the.*
bcb0: 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
bcc0: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
bcd0: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
bce0: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
bcf0: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
bd00: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
bd10: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
bd20: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
bd30: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
bd40: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
bd50: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
bd60: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
bd70: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
bd80: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
bd90: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
bda0: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
bdb0: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
bdc0: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
bdd0: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
bde0: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
bdf0: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
be00: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
be10: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
be20: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
be30: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
be40: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
be50: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
be60: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
be70: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
be80: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
be90: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
bea0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
beb0: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
bec0: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
bed0: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
bee0: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
bef0: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
bf00: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
bf10: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
bf20: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
bf30: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
bf40: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
bf50: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
bf60: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
bf70: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
bf80: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
bf90: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
bfa0: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
bfb0: 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
bfc0: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
bfd0: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
bfe0: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
bff0: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
c000: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
c010: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
c020: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
c030: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
c040: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
c050: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
c060: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
c070: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
c080: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
c090: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
c0a0: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
c0b0: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
c0c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
c0d0: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
c0e0: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
c0f0: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
c100: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
c110: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
c120: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
c130: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
c140: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
c150: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
c160: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
c170: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
c180: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
c190: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
c1a0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
c1b0: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
c1c0: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
c1d0: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
c1e0: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
c1f0: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
c200: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
c210: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
c220: 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
c230: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70  ** <a href="http
c240: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
c250: 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  g/cvstrac/wiki?p
c260: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
c270: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
c280: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
c290: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
c2a0: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
c2b0: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
c2c0: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
c2d0: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a   important..**..
c2e0: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
c2f0: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
c300: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
c310: 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ed for each data
c320: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
c330: 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  on.  Setting a n
c340: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
c350: 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69  clears any previ
c360: 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74  ous one. .** Not
c370: 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
c380: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
c390: 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73  eout()] will als
c3a0: 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a  o set or clear.*
c3b0: 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
c3c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  er..**.** INVARI
c3d0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
c3e0: 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
c3f0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
c400: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  ] function repla
c410: 63 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e  ces the busy han
c420: 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  dler.**         
c430: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
c440: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c450: 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
c460: 62 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20  by the 1st.**   
c470: 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
c480: 20 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79   with a new busy
c490: 20 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66   handler identif
c4a0: 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61  ied by the 2nd a
c4b0: 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20  nd 3rd.**       
c4c0: 20 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a     parameters..*
c4d0: 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68  *.** {F12312} Th
c4e0: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68  e default busy h
c4f0: 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64  andler for new d
c500: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c510: 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ons is NULL..**.
c520: 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e  ** {F12314} When
c530: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74   two or more dat
c540: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c550: 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
c560: 63 61 63 68 65 2c 0a 2a 2a 20 20 20 20 20 20 20  cache,.**       
c570: 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
c580: 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
c590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c5a0: 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
c5b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
c5c0: 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64  cache is invoked
c5d0: 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
c5e0: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
c5f0: 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36  k..**.** {F12316
c600: 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
c610: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
c620: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
c630: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20  the SQLite.**   
c640: 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
c650: 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
c660: 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
c670: 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
c680: 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
c690: 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
c6a0: 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69  12318} SQLite wi
c6b0: 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62  ll invokes the b
c6c0: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68  usy handler with
c6d0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 20 77 68   two argument wh
c6e0: 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ich.**          
c6f0: 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  are a copy of th
c700: 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69  e pointer suppli
c710: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
c720: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
c730: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
c740: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20  busy_handler()] 
c750: 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74  and a count of t
c760: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69  he number of pri
c770: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
c780: 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
c790: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
c7a0: 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
c7b0: 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a  ing event..**.**
c7c0: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
c7d0: 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 62  .** {U12319} A b
c7e0: 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f 75  usy handler shou
c7f0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73  ld not call clos
c800: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
c810: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
c820: 20 20 20 20 20 20 6f 72 20 70 72 65 70 61 72 65        or prepare
c830: 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  d statement that
c840: 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
c850: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
c860: 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
c870: 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
c880: 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
c890: 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
c8a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
c8b0: 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
c8c0: 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12340}.**.** T
c8d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
c8e0: 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
c8f0: 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
c900: 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74  handler].** that
c910: 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68   sleeps for a wh
c920: 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61  ile when a.** ta
c930: 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
c940: 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c  The handler will
c950: 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
c960: 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20  times until .** 
c970: 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
c980: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
c990: 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e  eeping have been
c9a0: 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20   done. {F12343} 
c9b0: 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69  After.** "ms" mi
c9c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
c9d0: 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64  eeping, the hand
c9e0: 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
c9f0: 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73  ich.** causes [s
ca00: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
ca10: 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  o return [SQLITE
ca20: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
ca30: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
ca40: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
ca50: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
ca60: 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
ca70: 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
ca80: 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
ca90: 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
caa0: 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
cab0: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
cac0: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
cad0: 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
cae0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
caf0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
cb00: 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
cb10: 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66   handler was def
cb20: 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67  ined  .** (using
cb30: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
cb40: 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
cb50: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
cb60: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
cb70: 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
cb80: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
cb90: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
cba0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31  S:.**.** {F12341
cbb0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
cbc0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
cbd0: 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65  unction override
cbe0: 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  s any prior.**  
cbf0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
cc00: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
cc10: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
cc20: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
cc30: 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
cc40: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
cc50: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cc60: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d  ..**.** {F12343}
cc70: 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
cc80: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
cc90: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
cca0: 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a  ] is less than.*
ccb0: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71  *          or eq
ccc0: 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65  ual to zero, the
ccd0: 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  n the busy handl
cce0: 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f  er is cleared so
ccf0: 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
cd00: 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
cd10: 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
cd20: 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
cd30: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
cd40: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d  ..**.** {F12344}
cd50: 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
cd60: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
cd70: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
cd80: 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
cd90: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
cda0: 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
cdb0: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74  y handler is set
cdc0: 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
cdd0: 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
cde0: 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
cdf0: 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46  method in the VF
ce00: 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69  S interface unti
ce10: 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  l either the.** 
ce20: 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c           lock cl
ce30: 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
ce40: 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
ce50: 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64  ep time reported
ce60: 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20   back.**        
ce70: 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78    by xSleep() ex
ce80: 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
ce90: 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
cea0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
ceb0: 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
cec0: 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
ced0: 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
cee0: 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
cef0: 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
cf00: 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65  F12370}.**.** De
cf10: 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
cf20: 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
cf30: 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
cf40: 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
cf50: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
cf60: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
cf70: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
cf80: 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
cf90: 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
cfa0: 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
cfb0: 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
cfc0: 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
cfd0: 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
cfe0: 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
cff0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
d000: 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
d010: 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
d020: 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
d030: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
d040: 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
d050: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
d060: 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
d070: 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
d080: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
d090: 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
d0a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
d0b0: 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
d0c0: 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
d0d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
d0e0: 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
d0f0: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
d100: 72 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61 72  rings.  There ar
d110: 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
d120: 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
d130: 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20    .** The first 
d140: 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
d150: 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
d160: 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
d170: 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68 65   .** contain the
d180: 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
d190: 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
d1a0: 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
d1b0: 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
d1c0: 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
d1d0: 4c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65 20  L.** values are 
d1e0: 67 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  give a NULL poin
d1f0: 74 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ter.  All other 
d200: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a 2a  values are in.**
d210: 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
d220: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
d230: 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
d240: 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
d250: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
d260: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
d270: 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
d280: 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
d290: 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s of one or more
d2a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d2b0: 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
d2c0: 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
d2d0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
d2e0: 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
d2f0: 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
d300: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
d310: 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
d320: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
d330: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
d340: 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
d350: 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
d360: 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
d370: 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
d380: 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
d390: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
d3a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
d3b0: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
d3c0: 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
d3d0: 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
d3e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d3f0: 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
d400: 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
d410: 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
d420: 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
d430: 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
d440: 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
d450: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
d460: 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
d470: 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
d480: 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
d490: 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
d4a0: 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
d4b0: 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
d4c0: 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
d4d0: 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
d4e0: 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
d4f0: 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
d500: 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
d510: 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
d520: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
d530: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
d540: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d550: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
d560: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d570: 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
d580: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d590: 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
d5a0: 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
d5b0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
d5c0: 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
d5d0: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
d5e0: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
d5f0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d600: 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
d610: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d620: 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
d630: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d640: 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
d650: 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
d660: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
d670: 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
d680: 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
d690: 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
d6a0: 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
d6b0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
d6c0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
d6d0: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
d6e0: 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
d6f0: 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
d700: 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65  arameter.  It re
d710: 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
d720: 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
d730: 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
d740: 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
d750: 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
d760: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
d770: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
d780: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
d790: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  t, it should .**
d7a0: 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
d7b0: 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20  r to the result 
d7c0: 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33  table to sqlite3
d7d0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
d7e0: 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65   order to .** re
d7f0: 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
d800: 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
d810: 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  -ed.  Because of
d820: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
d830: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
d840: 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
d850: 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
d860: 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
d870: 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
d880: 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
d890: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
d8a0: 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
d8b0: 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 74   Only .** [sqlit
d8c0: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
d8d0: 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
d8e0: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
d8f0: 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
d900: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
d910: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d920: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
d930: 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
d940: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
d950: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
d960: 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
d970: 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
d980: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
d990: 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
d9a0: 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
d9b0: 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
d9c0: 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
d9d0: 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
d9e0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
d9f0: 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
da00: 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
da10: 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
da20: 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
da30: 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
da40: 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
da50: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
da60: 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
da70: 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
da80: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
da90: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
daa0: 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
dab0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
dac0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
dad0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31  S:.**.** {F12371
dae0: 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
daf0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
db00: 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
db10: 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
db20: 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65           it free
db30: 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
db40: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
db50: 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68  ction, aborts th
db60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
db70: 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
db80: 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71  skips any subseq
db90: 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
dba0: 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
dbb0: 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70     *resultp outp
dbc0: 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
dbd0: 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b  LL and returns [
dbe0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
dbf0: 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66  *.** {F12373} If
dc00: 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72   the ncolumn par
dc10: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
dc20: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
dc30: 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
dc40: 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
dc50: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
dc60: 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d  )] write the num
dc70: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
dc80: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
dc90: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
dca0: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
dcb0: 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
dcc0: 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
dcd0: 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
dce0: 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
dcf0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
dd00: 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
dd10: 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
dd20: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
dd30: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
dd40: 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
dd50: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
dd60: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
dd70: 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e  e()] write the n
dd80: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
dd90: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
dda0: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
ddb0: 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
ddc0: 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79  row if the query
ddd0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
dde0: 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
ddf0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
de00: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
de10: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54  **.** {F12376} T
de20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
de30: 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f  table()] functio
de40: 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c  n sets its *ncol
de50: 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  umn value.**    
de60: 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 6d        to the num
de70: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
de80: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
de90: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
dea0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
deb0: 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c 20   sql parameter, 
dec0: 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68  or to zero if th
ded0: 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68  e query in sql h
dee0: 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 20  as an empty.**  
def0: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
df00: 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
df10: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
df20: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
df30: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
df40: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
df50: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
df60: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
df70: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
df80: 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74   char ***pResult
df90: 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  ,      /* Result
dfa0: 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
dfb0: 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20  /.  int *nrow,  
dfc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
dfd0: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
dfe0: 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
dff0: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d  */.  int *ncolum
e000: 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  n,         /* Nu
e010: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
e020: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
e030: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
e040: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f  errmsg         /
e050: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
e060: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
e070: 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
e080: 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
e090: 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
e0a0: 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
e0b0: 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
e0c0: 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37  g Functions {F17
e0d0: 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
e0e0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
e0f0: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
e100: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
e110: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
e120: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
e130: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
e140: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e150: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
e160: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
e170: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
e180: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
e190: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
e1a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
e1b0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
e1c0: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
e1d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
e1e0: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
e1f0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
e200: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
e210: 66 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 20  free()].   Both 
e220: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
e230: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
e240: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
e250: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
e260: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
e270: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
e280: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
e290: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
e2a0: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
e2b0: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
e2c0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
e2d0: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
e2e0: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
e2f0: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
e300: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
e310: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
e320: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
e330: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
e340: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
e350: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
e360: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
e370: 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
e380: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
e390: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
e3a0: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
e3b0: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
e3c0: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
e3d0: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
e3e0: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
e3f0: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
e400: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
e410: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
e420: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
e430: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
e440: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
e450: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
e460: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
e470: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
e480: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
e490: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
e4a0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
e4b0: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
e4c0: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
e4d0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
e4e0: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
e4f0: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
e500: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
e510: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
e520: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
e530: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
e540: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
e550: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
e560: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
e570: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
e580: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
e590: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
e5a0: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
e5b0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
e5c0: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
e5d0: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
e5e0: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
e5f0: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
e600: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
e610: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
e620: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
e630: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
e640: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
e650: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
e660: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
e670: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
e680: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
e690: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
e6a0: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
e6b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
e6c0: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
e6d0: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
e6e0: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
e6f0: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
e700: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
e710: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
e720: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
e730: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
e740: 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61  ual printf forma
e750: 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
e760: 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
e770: 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
e780: 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
e790: 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
e7a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
e7b0: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
e7c0: 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
e7d0: 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
e7e0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
e7f0: 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
e800: 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
e810: 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
e820: 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
e830: 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
e840: 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
e850: 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
e860: 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
e870: 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
e880: 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
e890: 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
e8a0: 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
e8b0: 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
e8c0: 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
e8d0: 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
e8e0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f   For example, so
e8f0: 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72   some string var
e900: 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  iable contains t
e910: 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
e920: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
e930: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
e940: 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
e950: 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
e960: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
e970: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
e980: 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
e990: 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
e9a0: 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
e9b0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
e9c0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
e9d0: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
e9e0: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
e9f0: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
ea00: 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
ea10: 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
ea20: 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
ea30: 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
ea40: 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
ea50: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
ea60: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
ea70: 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
ea80: 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
ea90: 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
eaa0: 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
eab0: 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
eac0: 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
ead0: 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
eae0: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
eaf0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
eb00: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
eb10: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
eb20: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
eb30: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
eb40: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
eb50: 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
eb60: 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
eb70: 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
eb80: 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
eb90: 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
eba0: 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
ebb0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
ebc0: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
ebd0: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
ebe0: 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
ebf0: 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
ec00: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
ec10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
ec20: 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
ec30: 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
ec40: 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
ec50: 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68  l rule you.** sh
ec60: 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20  ould always use 
ec70: 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
ec80: 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
ec90: 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
eca0: 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a  ng .** literal..
ecb0: 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
ecc0: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
ecd0: 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
ece0: 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
ecf0: 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
ed00: 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
ed10: 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
ed20: 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  Or if the parame
ed30: 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d  ter in the argum
ed40: 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61  ent.** list is a
ed50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
ed60: 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
ed70: 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
ed80: 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a  ithout single.**
ed90: 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
eda0: 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
edb0: 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66  on. {END}  So, f
edc0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
edd0: 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
ede0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
edf0: 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
ee00: 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
ee10: 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
ee20: 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
ee30: 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
ee40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
ee50: 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
ee60: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
ee70: 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
ee80: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
ee90: 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
eea0: 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
eeb0: 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
eec0: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
eed0: 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
eee0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
eef0: 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
ef00: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
ef10: 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f  *.** The "%z" fo
ef20: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
ef30: 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69  works exactly li
ef40: 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65  ke "%s" with the
ef50: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
ef60: 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
ef70: 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
ef80: 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
ef90: 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
efa0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
efb0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
efc0: 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20  e input string. 
efd0: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  {END}.**.** INVA
efe0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
eff0: 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17403}  The [sql
f000: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
f010: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70  and [sqlite3_vmp
f020: 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
f030: 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ces.**          
f040: 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 70   return either p
f050: 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
f060: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
f070: 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e   strings held in
f080: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65  .**           me
f090: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
f0a0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
f0b0: 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f  oc()] or NULL po
f0c0: 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20  inters if.**    
f0d0: 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f         a call to
f0e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f0f0: 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ()] fails..**.**
f100: 20 7b 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b   {F17406}  The [
f110: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
f120: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  ()] interface wr
f130: 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ites a zero-term
f140: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
f150: 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
f160: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
f170: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
f180: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f190: 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
f1a0: 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 74   provided that t
f1b0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f1c0: 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68  er is greater th
f1d0: 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  an zero..**.** {
f1e0: 46 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71  F17407}  The [sq
f1f0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
f200: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
f210: 20 6e 6f 74 20 77 72 69 74 65 73 20 73 6c 6f 74   not writes slot
f220: 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
f230: 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66    its output buf
f240: 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20  fer (the second 
f250: 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69  parameter) outsi
f260: 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20  de the range.** 
f270: 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74            of 0 t
f280: 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72  hrough N-1 (wher
f290: 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74  e N is the first
f2a0: 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20   parameter).**  
f2b0: 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c           regardl
f2c0: 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74  ess of the lengt
f2d0: 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a  h of the string.
f2e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71  **           req
f2f0: 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f  uested by the fo
f300: 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69  rmat specificati
f310: 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61  on..**   .*/.cha
f320: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
f330: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
f340: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
f350: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
f360: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
f370: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
f380: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
f390: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
f3a0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
f3b0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
f3c0: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
f3d0: 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a  tem {F17300}.**.
f3e0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f3f0: 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
f400: 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
f410: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
f420: 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
f430: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
f440: 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
f450: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
f460: 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
f470: 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
f480: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f490: 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
f4a0: 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
f4b0: 77 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  windows VFS uses
f4c0: 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20 61   native malloc a
f4d0: 6e 64 20 66 72 65 65 20 66 6f 72 20 73 6f 6d 65  nd free for some
f4e0: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
f4f0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
f500: 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
f510: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
f520: 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
f530: 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
f540: 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
f550: 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
f560: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
f570: 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
f580: 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
f590: 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
f5a0: 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
f5b0: 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
f5c0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
f5d0: 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
f5e0: 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
f5f0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
f600: 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
f610: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
f620: 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
f630: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
f640: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
f650: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
f660: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
f670: 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
f680: 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
f690: 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
f6a0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
f6b0: 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
f6c0: 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
f6d0: 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
f6e0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
f6f0: 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
f700: 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
f710: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
f720: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
f730: 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
f740: 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
f750: 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
f760: 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
f770: 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
f780: 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
f790: 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
f7a0: 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
f7b0: 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
f7c0: 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
f7d0: 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
f7e0: 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
f7f0: 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
f800: 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
f810: 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
f820: 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
f830: 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
f840: 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
f850: 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
f860: 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
f870: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
f880: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
f890: 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
f8a0: 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
f8b0: 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
f8c0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72  () or sqlite3_fr
f8d0: 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ee()..**.** The 
f8e0: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
f8f0: 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
f900: 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
f910: 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
f920: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
f930: 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
f940: 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
f950: 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
f960: 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
f970: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f980: 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
f990: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
f9a0: 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20  ameter.  If the 
f9b0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f9c0: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
f9d0: 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
f9e0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
f9f0: 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
fa00: 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
fa10: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
fa20: 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
fa30: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
fa40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
fa50: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
fa60: 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * If the second 
fa70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
fa80: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
fa90: 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
faa0: 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
fab0: 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
fac0: 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
fad0: 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
fae0: 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
faf0: 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
fb00: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
fb10: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
fb20: 2a 20 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * Sqlite3_reallo
fb30: 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
fb40: 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
fb50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
fb60: 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
fb70: 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
fb80: 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
fb90: 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
fba0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d  ailable..** If M
fbb0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
fbc0: 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
fbd0: 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
fbe0: 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
fbf0: 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
fc00: 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
fc10: 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
fc20: 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
fc30: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
fc40: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
fc50: 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
fc60: 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
fc70: 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72  .** If sqlite3_r
fc80: 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
fc90: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
fca0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
fcb0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
fcc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  ..**.** The memo
fcd0: 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
fce0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
fcf0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
fd00: 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
fd10: 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
fd20: 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
fd30: 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d   boundary. {END}
fd40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
fd50: 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  lt implementatio
fd60: 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f  n.** of the memo
fd70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
fd80: 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65  bsystem uses the
fd90: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
fda0: 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65  oc().** and free
fdb0: 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
fdc0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
fdd0: 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20  brary. {F17382} 
fde0: 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20  However, if .** 
fdf0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
fe00: 65 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c  ed with the foll
fe10: 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65  owing C preproce
fe20: 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a  ssor macro.**.**
fe30: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51   <blockquote> SQ
fe40: 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
fe50: 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c  =<i>NNN</i> </bl
fe60: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
fe70: 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
fe80: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   is an integer, 
fe90: 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
fea0: 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61  te a static.** a
feb0: 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74  rray of at least
fec0: 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
fed0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
fee0: 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20  e that array.** 
fef0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
ff00: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
ff10: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
ff20: 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
ff30: 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  l.** memory allo
ff40: 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61  cator options ma
ff50: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ff60: 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
ff70: 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
ff80: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
ff90: 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
ffa0: 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
ffb0: 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
ffc0: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
ffd0: 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
ffe0: 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
fff0: 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
10000 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
10010 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10020 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
10030 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
10040 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
10050 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
10060 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
10070 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75  tors can be.** u
10080 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 77  sed..**.** The w
10090 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
100a0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
100b0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
100c0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
100d0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
100e0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
100f0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
10100 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
10110 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
10120 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
10130 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
10140 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
10150 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 69  he particular wi
10160 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
10170 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
10180 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
10190 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
101a0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
101b0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
101c0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
101d0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
101e0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
101f0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
10200 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
10210 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  NTS:.**.** {F173
10220 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
10230 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
10240 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
10250 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20  ither a pointer 
10260 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
10270 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f   newly checked-o
10280 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c  ut block of at l
10290 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  east N bytes of 
102a0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
102b0 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79      that is 8-by
102c0 74 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20  te aligned, .** 
102d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 74 20            or it 
102e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
102f0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10300 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75  fulfill the requ
10310 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  est..**.** {F173
10320 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  04}  The [sqlite
10330 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
10340 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
10350 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
10360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20  .**           N 
10370 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
10380 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a  equal to zero..*
10390 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 54  *.** {F17305}  T
103a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  he [sqlite3_free
103b0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (P)] interface r
103c0 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70  eleases memory p
103d0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
103e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
103f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
10400 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
10410 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
10420 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b  **           mak
10430 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65  ing it available
10440 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a   for reuse..**.*
10450 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63 61  * {F17306}  A ca
10460 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
10470 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20  ree(NULL)] is a 
10480 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
10490 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20  **.** {F17310}  
104a0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
104b0 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d  e3_realloc(0,N)]
104c0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
104d0 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
104e0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
104f0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a  3_malloc(N)]..**
10500 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 20  .** {F17312}  A 
10510 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
10520 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69  _realloc(P,0)] i
10530 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
10540 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
10550 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
10560 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20  free(P)]..**.** 
10570 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20 53 51  {F17315}  The SQ
10580 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b  Lite core uses [
10590 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
105a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  ], [sqlite3_real
105b0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
105c0 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65       and [sqlite
105d0 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c  3_free()] for al
105e0 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20  l of its memory 
105f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a  allocation and.*
10600 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c  *           deal
10610 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
10620 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20  **.** {F17318}  
10630 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  The [sqlite3_rea
10640 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72  lloc(P,N)] inter
10650 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
10660 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  her a pointer.**
10670 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20             to a 
10680 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64  block of checked
10690 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61  -out memory of a
106a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
106b0 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20  in size.**      
106c0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
106d0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
106e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
106f0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20  **.** {F17321}  
10700 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
10710 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
10720 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
10730 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
10740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
10750 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b  pies the first K
10760 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e   bytes of conten
10770 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68  t from P into th
10780 65 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74 65  e newly allocate
10790 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77  d.**           w
107a0 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65  here K is the le
107b0 73 73 6f 72 20 6f 66 20 4e 20 61 6e 64 20 74 68  ssor of N and th
107c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
107d0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
107e0 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71  17322}  When [sq
107f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10800 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
10810 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
10820 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
10830 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74        releases t
10840 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  he buffer P..**.
10850 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65  ** {F17323}  Whe
10860 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
10870 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
10880 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65   NULL, the buffe
10890 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  r P is.**       
108a0 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64      not modified
108b0 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a   or released..**
108c0 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
108d0 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20  .**.** {U17350} 
108e0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
108f0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
10900 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
10910 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10920 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
10930 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
10940 55 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20 70 6f  ULL or else a po
10950 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 20 66  inter obtained f
10960 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
10970 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
10980 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
10990 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
109a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
109b0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 20 20 20   that has.**    
109c0 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
109d0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
109e0 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {U17351}  The ap
109f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10a00 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
10a10 20 61 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a   any part of .**
10a20 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f             a blo
10a30 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
10a40 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
10a50 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
10a60 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
10a70 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
10a80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10a90 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a  )]..**.*/.void *
10aa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
10ab0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
10ac0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
10ad0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
10ae0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
10af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10b00 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10b10 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
10b20 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F17370}.**.** SQ
10b30 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
10b40 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
10b50 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
10b60 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
10b70 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
10b80 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
10b90 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
10ba0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
10bb0 6c 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d 65  loc()].** the me
10bc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10bd0 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64  subsystem includ
10be0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 53 51  ed within the SQ
10bf0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  Lite..**.** INVA
10c00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
10c10 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
10c20 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10c30 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
10c40 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
10c50 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
10c60 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  es of memory cur
10c70 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
10c80 6e 67 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ng .**          
10c90 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
10ca0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
10cb0 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {F17373} The [sq
10cc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10cd0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
10ce0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
10cf0 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
10d00 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
10d10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10d20 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )] .**          
10d30 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 77 61  since the highwa
10d40 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73  ter mark was las
10d50 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
10d60 46 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  F17374} The valu
10d70 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
10d80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
10d90 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
10da0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10db0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
10dc0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
10dd0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
10de0 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
10df0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
10e00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
10e10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10e20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
10e30 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
10e40 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
10e50 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
10e60 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
10e70 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
10e80 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
10e90 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
10ea0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d  .** .** {F17375}
10eb0 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
10ec0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
10ed0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
10ee0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
10ef0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
10f00 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
10f10 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
10f20 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
10f30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10f40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10f50 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
10f60 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
10f70 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
10f80 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
10f90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
10fa0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 77 61  )] is the highwa
10fb0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
10fc0 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
10fd0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
10fe0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
10ff0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
11000 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
11010 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
11020 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
11030 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
11040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
11050 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
11060 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37  r Generator {F17
11070 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  390}.**.** SQLit
11080 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
11090 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
110a0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
110b0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
110c0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
110d0 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
110e0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
110f0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
11100 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
11110 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
11120 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
11130 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
11140 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
11150 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
11160 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
11170 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
11180 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
11190 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
111a0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 61 74 69 6f  ows.** appliatio
111b0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
111c0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
111d0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
111e0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
111f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
11200 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
11210 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
11220 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
11230 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
11240 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
11250 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
11260 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
11270 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11280 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
11290 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
112a0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
112b0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
112c0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
112d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
112e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
112f0 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
11300 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
11310 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
11320 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
11330 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
11340 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
11350 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
11360 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
11370 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
11380 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
11390 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
113a0 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  F17392} The [sql
113b0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
113c0 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
113d0 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
113e0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
113f0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
11400 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
11410 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
11420 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
11430 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
11440 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
11450 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
11460 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
11470 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
11480 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12500}.**.** Thi
11490 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
114a0 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
114b0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
114c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
114d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
114e0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
114f0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11500 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
11510 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11520 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
11530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
11540 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
11550 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
11560 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
11570 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
11580 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
11590 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
115a0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
115b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
115c0 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
115d0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
115e0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
115f0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
11600 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
11610 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
11620 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
11630 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
11640 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11650 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
11660 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
11670 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
11680 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
11690 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
116a0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
116b0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
116c0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
116d0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
116e0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
116f0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
11700 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
11710 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
11720 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
11730 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
11740 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
11750 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
11760 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
11770 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
11780 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
11790 20 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72     If the author
117a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
117b0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
117c0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
117d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
117e0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
117f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
11800 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  then [sqlite3_pr
11810 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
11820 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
11830 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
11840 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11850 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
11860 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
11870 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
11880 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
11890 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
118a0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
118b0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
118c0 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
118d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
118e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
118f0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
11900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
11910 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
11920 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
11930 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
11940 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
11950 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
11960 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
11970 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
11980 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20   is denied.  If 
11990 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
119a0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
119b0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
119c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
119d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
119e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
119f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a00 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
11a10 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
11a20 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
11a30 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
11a40 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
11a50 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
11a60 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
11a70 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
11a80 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
11a90 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
11aa0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
11ab0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
11ac0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
11ad0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
11ae0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
11af0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
11b00 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  able..**.** The 
11b10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11b20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
11b30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
11b40 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
11b50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
11b60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
11b70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
11b80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
11b90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
11ba0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
11bb0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
11bc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
11bd0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
11be0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
11bf0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
11c00 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75  tion.** to be au
11c10 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
11c20 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
11c30 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  h.** parameters 
11c40 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
11c50 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
11c60 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
11c70 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64   contain .** add
11c80 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
11c90 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
11ca0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
11cb0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
11cc0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
11cd0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
11ce0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
11cf0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
11d00 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
11d10 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c  usted.** source,
11d20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
11d30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
11d40 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ts do not try to
11d50 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20   access data.** 
11d60 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f  that they are no
11d70 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
11d80 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
11d90 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20  o not try to.** 
11da0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
11db0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
11dc0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
11dd0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
11de0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
11df0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
11e00 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
11e10 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
11e20 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
11e30 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
11e40 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
11e50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
11e60 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
11e70 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
11e80 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
11e90 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
11ea0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
11eb0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
11ec0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
11ed0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
11ee0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
11ef0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
11f00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11f10 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
11f20 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
11f30 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
11f40 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
11f50 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
11f60 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
11f70 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
11f80 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
11f90 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
11fa0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
11fb0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
11fc0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
11fd0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
11fe0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
11ff0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
12000 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
12010 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
12020 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
12030 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
12040 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
12050 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
12060 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
12070 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
12080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12090 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
120a0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
120b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
120c0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
120d0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
120e0 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
120f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
12100 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
12110 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
12120 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
12130 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
12140 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  fault..**.** Not
12150 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
12160 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
12170 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
12180 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  uring .** [sqlit
12190 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
121a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
121b0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
121c0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
121d0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
121e0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
121f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
12200 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
12210 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  NTS:.**.** {F125
12220 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
12230 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
12240 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
12250 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a  e registers a.**
12260 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
12270 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
12280 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  th database conn
12290 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
122a0 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 74  {F12502} The aut
122b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
122c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
122d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
122e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
122f0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a  ing compiled.**.
12300 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20 74  ** {F12503} If t
12310 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
12320 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
12330 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
12340 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
12350 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
12360 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
12370 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
12380 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
12390 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
123a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
123b0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
123c0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
123d0 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
123e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
123f0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
12400 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
12410 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
12420 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
12430 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
12440 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
12450 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57  **.** {F12504} W
12460 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
12470 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
12480 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
12490 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
124a0 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
124b0 69 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e 6f  ibed is coded no
124c0 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rmally..**.** {F
124d0 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
124e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
124f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
12500 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
12510 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
12520 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
12530 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
12540 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
12550 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
12560 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12570 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
12580 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
12590 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
125a0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
125b0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
125c0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
125d0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
125e0 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
125f0 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  denied..**.** {F
12600 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
12610 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
12620 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
12630 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
12640 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
12650 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
12660 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
12670 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12680 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
12690 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
126a0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
126b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
126c0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
126d0 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  cted to.**      
126e0 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c      insert a NUL
126f0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
12700 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
12710 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
12720 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
12730 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
12740 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
12750 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  en returned..**.
12760 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74  ** {F12507} If t
12770 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
12780 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
12790 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
127a0 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
127b0 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
127c0 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
127d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41  than [SQLITE_REA
127e0 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  D], then.**     
127f0 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66       a return of
12800 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
12810 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66   has the same ef
12820 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f  fect as [SQLITE_
12830 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  DENY]. .**.** {F
12840 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
12850 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12860 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12870 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
12880 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
12890 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
128a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
128b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
128c0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
128d0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54  **.** {F12511} T
128e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
128f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
12900 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
12910 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  r .**          [
12920 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
12930 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
12940 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
12950 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
12960 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62  **          to b
12970 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
12980 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65  .** {F12512} The
12990 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
129a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
129b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
129c0 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
129d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
129e0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
129f0 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  tain .**        
12a00 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
12a10 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
12a20 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
12a30 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
12a40 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
12a50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
12a60 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
12a70 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
12a80 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65           any pre
12a90 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65  viously installe
12aa0 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  d authorizer..**
12ab0 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 4e  .** {F12521} A N
12ac0 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
12ad0 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
12ae0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20  horization.**   
12af0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
12b00 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
12b10 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 64  * {F12522} The d
12b20 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65  efault authorize
12b30 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  r is NULL..*/.in
12b40 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
12b50 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
12b60 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
12b70 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
12b80 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
12b90 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
12ba0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
12bb0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
12bc0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
12bd0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
12be0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
12bf0 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12590}.**.** Th
12c00 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
12c10 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
12c20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12c30 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
12c40 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
12c50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
12c60 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
12c70 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
12c80 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
12c90 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
12ca0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
12cb0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
12cc0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
12cd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12ce0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
12cf0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
12d00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
12d10 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
12d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12d30 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
12d40 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
12d50 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
12d60 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
12d70 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
12d80 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
12d90 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
12da0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
12db0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
12dc0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
12dd0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20  er Action Codes 
12de0 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12550}.**.** T
12df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
12e00 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
12e10 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
12e20 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
12e30 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
12e40 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
12e50 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53  orizer certain S
12e60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
12e70 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
12e80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
12e90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
12ea0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
12eb0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
12ec0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
12ed0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
12ee0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
12ef0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
12f00 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
12f10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
12f20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
12f30 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
12f40 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
12f50 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
12f60 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
12f70 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a  ation is to be .
12f80 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
12f90 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
12fa0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12fb0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
12fc0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
12fd0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
12fe0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
12ff0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
13000 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
13010 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
13020 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13030 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
13040 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
13050 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
13060 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
13070 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
13080 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
13090 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66  p", .** etc.) if
130a0 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68   applicable.  Th
130b0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
130c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
130d0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
130e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
130f0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
13100 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
13110 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
13120 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
13130 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
13140 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
13150 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
13160 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f  ctly from .** to
13170 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
13180 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
13190 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35  TS:.**.** {F1255
131a0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
131b0 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a  rameter to an .*
131c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
131d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
131e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
131f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6c 77 61  callback is alwa
13200 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  ys an integer.**
13210 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
13220 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69  E_COPY | authori
13230 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73  zer code] that s
13240 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63  pecifies what ac
13250 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
13260 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
13270 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
13280 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64  552} The 3rd and
13290 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
132a0 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  to the .**      
132b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
132c0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
132d0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
132e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a  back function].*
132f0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
13300 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
13310 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
13320 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20  on which .**    
13330 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
13340 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
13350 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73  code] is used as
13360 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
13370 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
13380 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61  2553} The 5th pa
13390 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
133a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
133b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
133c0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
133d0 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
133e0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
133f0 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73    of the databas
13400 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69  e (example: "mai
13410 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e  n", "temp", etc.
13420 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
13430 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20  .**.** {F12554} 
13440 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
13450 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
13460 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
13470 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
13480 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
13490 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a  ck] is the name.
134a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
134b0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
134c0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
134d0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
134e0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
134f0 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74    the access att
13500 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
13510 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
13520 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
13530 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  from .**        
13540 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20    top-level SQL 
13550 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  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 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
13590 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
135a0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
135b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
135c0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
135d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
135e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
135f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13600 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
13610 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
13620 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13650 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
13660 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
13670 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
13680 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
13690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
136a0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
136b0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
136c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
136d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
136e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
136f0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
13700 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
13710 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
13720 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13740 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
13750 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
13760 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
13770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13790 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
137a0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
137b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
137c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
137d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
137e0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
137f0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
13800 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
13810 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13830 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
13840 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
13850 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
13860 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
13880 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
13890 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
138a0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
138b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
138c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
138d0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
138e0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
138f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13900 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13910 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
13920 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
13930 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
13940 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
13950 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
13960 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
13970 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
13980 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
13990 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
139a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
139b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
139c0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
139d0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
139e0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
139f0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
13a00 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
13a10 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
13a20 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
13a30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13a40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13a50 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
13a60 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
13a70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
13a80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
13a90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13aa0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
13ab0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
13ac0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13ad0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13ae0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13af0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
13b00 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
13b10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13b20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13b30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13b40 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
13b50 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
13b60 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
13b70 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
13b80 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
13b90 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
13ba0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
13bb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13bc0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
13bd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13be0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
13bf0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
13c00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13c10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13c30 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
13c40 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
13c50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
13c60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13c80 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
13c90 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
13ca0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
13cb0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
13cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13cd0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
13ce0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
13cf0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
13d00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13d10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13d20 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
13d30 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
13d40 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
13d50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
13d70 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
13d80 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
13d90 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
13da0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
13db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
13dc0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
13dd0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
13de0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13df0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
13e10 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
13e20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
13e30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13e40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13e50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13e60 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
13e70 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
13e80 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
13e90 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
13ea0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
13eb0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
13ec0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
13ed0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
13ee0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
13ef0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
13f00 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
13f10 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
13f20 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
13f30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13f40 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
13f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
13f60 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
13f70 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
13f80 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
13f90 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
13fa0 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d  nctions {F12280}
13fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13fc0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
13fd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
13fe0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
13ff0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
14000 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
14010 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
14020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
14030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
14040 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
14050 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
14060 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
14070 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
14080 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
14090 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
140a0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
140b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
140c0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
140d0 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d  k returns a UTF-
140e0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
140f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14100 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20   text.** as the 
14110 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
14120 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
14130 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61  .  Additional ca
14140 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a  llbacks occur.**
14150 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
14160 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
14170 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
14180 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
14190 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
141a0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
141b0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
141c0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  s the trigger..*
141d0 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  * .** The callba
141e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
141f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
14200 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
14210 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
14220 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
14230 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
14240 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
14250 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
14260 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
14270 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
14280 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
14290 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
142a0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
142b0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
142c0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
142d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
142e0 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74  ) API is current
142f0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
14300 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a  perimental and.*
14310 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  * is subject to 
14320 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
14330 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  l in a future re
14340 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lease..**.** The
14350 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69   trigger reporti
14360 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68  ng feature of th
14370 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
14380 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a   is considered.*
14390 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  * experimental a
143a0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
143b0 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
143c0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
143d0 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65  eases..** Future
143e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
143f0 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
14400 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c  dd new trace cal
14410 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61  lback .** invoca
14420 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
14430 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
14440 46 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c  F12281} The call
14450 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
14460 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
14470 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73  ite3_trace()] is
14480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
14490 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61  never an SQL sta
144a0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
144b0 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61  ins to execute a
144c0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
144d0 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65  henever a trigge
144e0 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72  r subprogram fir
144f0 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e  st begins to run
14500 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d  ..**.** {F12282}
14510 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
14520 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
14530 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72  overrides the pr
14540 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20  eviously.**     
14550 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
14560 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  trace callback..
14570 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41  **.** {F12283} A
14580 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c   NULL trace call
14590 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72  back disables tr
145a0 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  acing..**.** {F1
145b0 32 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20  2284} The first 
145c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
145d0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
145e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
145f0 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e          the poin
14600 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
14610 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
14620 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
14630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ()]..**.** {F122
14640 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61  85} The second a
14650 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
14660 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
14670 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
14680 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14690 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  TF8 string conta
146a0 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
146b0 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
146c0 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
146d0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
146e0 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
146f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14700 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
14710 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
14720 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
14730 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
14740 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
14750 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
14760 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
14770 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ram..**.** {F122
14780 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
14790 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
147a0 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
147b0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
147c0 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
147d0 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
147e0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
147f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38  s..**.** {F12288
14800 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
14810 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
14820 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
14830 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
14840 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
14850 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
14860 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
14870 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20  .**.** {F12289} 
14880 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14890 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
148a0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
148b0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
148c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
148d0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
148e0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
148f0 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
14900 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
14910 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
14920 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
14930 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
14940 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
14950 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
14960 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
14970 46 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  F12290} The thir
14980 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
14990 68 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c  he profile  call
149a0 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d  back is an estim
149b0 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
149c0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
149d0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20   nanoseconds of 
149e0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20  wall-clock time 
149f0 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20  required to.**  
14a00 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20          run the 
14a10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72  SQL statement fr
14a20 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69  om start to fini
14a30 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  sh..*/.void *sql
14a40 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
14a50 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
14a60 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
14a70 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  har*), void*);.v
14a80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
14a90 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
14aa0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
14ab0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
14ac0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
14ad0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
14ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
14af0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
14b00 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a  lbacks {F12910}.
14b10 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
14b20 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
14b30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14b40 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
14b50 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
14b60 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
14b70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
14b80 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
14b90 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
14ba0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
14bb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
14bc0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
14bd0 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 41  et_table()].   A
14be0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
14bf0 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72  r this .** inter
14c00 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
14c10 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
14c20 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
14c30 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ry..**.** If the
14c40 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
14c50 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
14c60 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 74 69 6f  ero, the opertio
14c70 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
14c80 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
14c90 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
14ca0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
14cb0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
14cc0 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
14cd0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
14ce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
14cf0 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
14d00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
14d10 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
14d20 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14d30 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
14d40 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
14d50 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
14d60 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
14d70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
14d80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
14d90 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ep()]..**.** {F1
14da0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
14db0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
14dc0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
14dd0 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
14de0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
14df0 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
14e00 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
14e10 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a  nd argument to .
14e20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
14e30 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
14e40 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
14e50 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
14e60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
14e70 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f  e callback.  <to
14e80 64 6f 3e 57 68 61 74 20 69 66 20 4e 20 69 73 20  do>What if N is 
14e90 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f  less than 1?</to
14ea0 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  do>.**.** {F1291
14eb0 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
14ec0 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
14ed0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
14ee0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
14ef0 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
14f00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
14f10 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e  ress_handler()].
14f20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20  .**.** {F12914} 
14f30 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
14f40 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  ent [sqlite3_pro
14f50 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
14f60 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20   is a.***       
14f70 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
14f80 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
14f90 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
14fa0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
14fb0 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
14fc0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14fd0 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
14fe0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
14ff0 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
15000 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a  s in fewer than.
15010 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70  **          N op
15020 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
15030 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  uted,.**        
15040 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72    then the progr
15050 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
15060 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b  never invoked. {
15070 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32  END}.** .** {F12
15080 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20  916} Every call 
15090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
150a0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
150b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
150c0 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69  writes any previ
150d0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 20  ously registere 
150e0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
150f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d  ..**.** {F12917}
15100 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
15110 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
15120 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
15130 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
15140 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
15150 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
15160 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65   {F12918} If the
15170 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
15180 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
15190 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
151a0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
151b0 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
151c0 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
151d0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
151e0 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
151f0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
15200 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
15210 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
15220 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
15230 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
15240 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
15250 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
15260 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30  nnection {F12700
15270 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
15280 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
15290 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
152a0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a  ile whose name.*
152b0 2a 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  * is given by th
152c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
152d0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ent..** The file
152e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
152f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15300 55 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71  UTF-8.** for [sq
15310 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
15320 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
15330 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46  v2()] and as UTF
15340 2d 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  -16.** in the na
15350 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
15360 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
15370 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73  n16()]..** An [s
15380 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
15390 69 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  is usually retur
153a0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
153b0 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f  en.** if an erro
153c0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
153d0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
153e0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
153f0 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63  able.** to alloc
15400 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
15410 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
15420 20 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20   object, a NULL 
15430 77 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74  will.** be writt
15440 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
15450 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
15460 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
15470 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49  e3] object..** I
15480 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
15490 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
154a0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63   created).** suc
154b0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20  cessfully, then 
154c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
154d0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
154e0 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ise an.** error 
154f0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
15500 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
15510 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
15520 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
15530 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63  6()]  routines c
15540 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
15550 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
15560 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
15570 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
15580 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
15590 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
155a0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
155b0 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
155c0 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  if.** [sqlite3_o
155d0 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
155e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
155f0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
15600 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
15610 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
15620 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  f [sqlite3_open1
15630 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a  6()] is used..**
15640 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
15650 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
15660 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
15670 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
15680 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
15690 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  th the [sqlite3*
156a0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
156b0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70  be released by p
156c0 61 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f 20  assing it.** to 
156d0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
156e0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
156f0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
15700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
15710 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
15720 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
15730 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ike [sqlite3_ope
15740 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20  n()] .** except 
15750 74 68 61 74 20 69 74 20 61 63 63 63 65 70 74 73  that it acccepts
15760 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
15770 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
15780 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
15790 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
157a0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
157b0 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
157c0 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
157d0 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a  be.** one of:.**
157e0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
157f0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
15800 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e  EADONLY].** <li>
15810 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
15820 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69  EADWRITE].** <li
15830 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
15840 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
15850 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
15860 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ol>.**.**
15870 20 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 65   The first value
15880 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
15890 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a  ase read-only. .
158a0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
158b0 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76  se does not prev
158c0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
158d0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
158e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
158f0 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  d option opens.*
15900 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
15910 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
15920 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
15930 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f  le, or reading o
15940 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65  nly if.** if the
15950 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
15960 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69  rotected.  In ei
15970 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64 61  ther case the da
15980 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61  tabase.** must a
15990 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f 72 20  lready exist or 
159a0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
159b0 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  rned.  The third
159c0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73   option.** opens
159d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
159e0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
159f0 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65  iting and create
15a00 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a  s it if it does.
15a10 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  ** not already e
15a20 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69  xist..** The thi
15a30 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65  rd options is be
15a40 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
15a50 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b  lways used for [
15a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
15a70 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
15a80 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
15a90 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
15aa0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
15ab0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
15ac0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
15ad0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
15ae0 68 6f 77 6e 20 61 62 6f 76 65 20 74 68 65 6e 20  hown above then 
15af0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
15b00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
15b10 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
15b20 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
15b30 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a  then an private.
15b40 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ** in-memory dat
15b50 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
15b60 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
15b70 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
15b80 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
15b90 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
15ba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15bb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
15bc0 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  sed.  Future.** 
15bd0 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
15be0 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65  e might make use
15bf0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
15c00 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
15c10 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77  .** that begin w
15c20 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
15c30 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65  acter.  It is re
15c40 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a  commended that .
15c50 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ** when a databa
15c60 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c  se filename real
15c70 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
15c80 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79  th.** ":" that y
15c90 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ou prefix the fi
15ca0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
15cb0 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22  thname like "./"
15cc0 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62   to.** avoid amb
15cd0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
15ce0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
15cf0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
15d00 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
15d10 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
15d20 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
15d30 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
15d40 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
15d50 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
15d60 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
15d70 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
15d80 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
15d90 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
15da0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
15db0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
15dd0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
15de0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
15df0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
15e00 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
15e10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
15e20 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  em .** interface
15e30 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61   that the new da
15e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15e50 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
15e60 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15e70 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e  parameter is a N
15e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
15e90 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
15ea0 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62  lite3_vfs].** ob
15eb0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
15ec0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77  .** <b>Note to w
15ed0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
15ee0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
15ef0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
15f00 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
15f10 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * of [sqlite3_op
15f20 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
15f30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75  e3_open_v2()] mu
15f40 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
15f50 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
15f60 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
15f70 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
15f80 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
15f90 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
15fa0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
15fb0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
15fc0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
15fd0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
15fe0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
15ff0 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
16000 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
16010 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16020 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d  :.**.** {F12701}
16030 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
16040 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
16050 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
16060 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
16080 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65  nterfaces create
16090 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
160a0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
160b0 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  nection] associa
160c0 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ted with.**     
160d0 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73       the databas
160e0 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20  e file given in 
160f0 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61  their first para
16100 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
16110 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61  2702} The filena
16120 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
16130 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
16140 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
16150 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
16160 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
16170 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
16180 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20   as UTF-16.**   
16190 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
161a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
161b0 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
161c0 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n16()]..**.** {F
161d0 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73  12703} A success
161e0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
161f0 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
16200 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16210 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20  n16()], .**     
16220 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
16230 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74  _open_v2()] writ
16240 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
16250 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
16260 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
16270 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70  ection] into *pp
16280 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  Db..**.** {F1270
16290 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
162a0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
162b0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
162c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
162d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
162e0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
162f0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75  rn [SQLITE_OK] u
16300 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20  pon success,.** 
16310 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61           or an a
16320 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
16330 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
16340 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  re..**.** {F1270
16350 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  6} The default t
16360 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
16370 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
16380 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
16390 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
163a0 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
163b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
163c0 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e  ] will be UTF-8.
163d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20  .**.** {F12707} 
163e0 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
163f0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
16400 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
16410 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
16420 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16430 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62  open16()] will b
16440 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
16450 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71  {F12709} The [sq
16460 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d  lite3_open(F,D)]
16470 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
16480 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20  uivalent to.**  
16490 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
164a0 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30  _open_v2(F,D,G,0
164b0 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70  )] where the G p
164c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
164d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
164e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c  OPEN_READWRITE]|
164f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
16500 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ATE]..**.** {F12
16510 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61  711} If the G pa
16520 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16530 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
16540 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
16550 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
16560 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
16570 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
16580 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
16590 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
165a0 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
165b0 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ing only..**.** 
165c0 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 20  {F12712} If the 
165d0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
165e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
165f0 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
16600 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
16610 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
16620 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
16630 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61  ITE] then the da
16640 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
16660 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
16670 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
16680 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
16690 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y if the.**     
166a0 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69       file is wri
166b0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
166c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
166d0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  stem..**.** {F12
166e0 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61  713} If the G pa
166f0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16700 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
16710 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a  G,V)] omits the.
16720 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
16730 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
16740 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
16750 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
16760 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
16770 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
16780 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
16790 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
167a0 46 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47  F12714} If the G
167b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
167c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
167d0 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
167e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
167f0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
16800 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
16810 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
16820 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
16830 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
16840 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e  y exist, then an
16850 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
16860 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a   to create and.*
16870 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69  *          initi
16880 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61  alize the databa
16890 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  se..**.** {F1271
168a0 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
168b0 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
168c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
168d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
168e0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
168f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
16900 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d  n_v2()] is ":mem
16910 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
16920 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
16930 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69      ephemeral, i
16940 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
16950 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
16960 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
16970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
16980 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
16990 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
169a0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
169b0 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
169c0 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
169d0 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
169e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20  .**.** {F12719} 
169f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
16a00 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
16a10 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
16a20 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20   a private,.**  
16a30 20 20 20 20 20 20 20 20 65 70 68 65 72 6d 65 72          ephermer
16a40 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
16a50 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
16a60 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
16a70 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
16a80 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
16a90 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
16aa0 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
16ab0 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
16ac0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
16ad0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  odo>.**.** {F127
16ae0 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
16af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
16b00 65 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20 20  eated by .**    
16b10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
16b20 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
16b30 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a   will use the.**
16b40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16b50 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
16b60 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
16b70 20 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72   V parameter, or
16b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
16b90 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
16ba0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
16bb0 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
16bc0 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
16bd0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
16be0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
16bf0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16c00 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
16c10 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16c20 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
16c30 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16c40 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
16c50 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
16c60 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
16c70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
16c80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
16c90 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
16ca0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
16cb0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
16cc0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16cd0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
16ce0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
16cf0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
16d00 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16d10 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
16d20 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16d30 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
16d40 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16d50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
16d60 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
16d70 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
16d80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
16d90 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
16da0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
16db0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
16dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
16dd0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
16de0 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d  essages {F12800}
16df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
16e00 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
16e10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
16e20 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
16e30 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
16e40 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
16e50 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
16e60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16e70 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
16e80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
16e90 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
16ea0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
16eb0 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
16ec0 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
16ed0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
16ee0 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
16ef0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
16f00 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
16f10 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
16f20 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
16f30 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
16f40 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
16f50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16f60 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
16f70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
16f80 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
16f90 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
16fa0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
16fb0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
16fc0 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
16fd0 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
16fe0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
16ff0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
17000 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
17010 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
17020 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
17030 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
17040 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69  need to worry wi
17050 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  th freeing the r
17060 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
17070 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
17080 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
17090 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
170a0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
170b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
170c0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
170d0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
170e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
170f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
17100 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
17110 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
17120 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17130 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
17140 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
17150 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
17160 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
17170 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
17180 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
17190 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20  esult code].**  
171a0 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
171b0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61  most recently fa
171c0 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
171d0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
171e0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
171f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17200 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
17210 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  F12803} The [sql
17220 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
17230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
17240 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
17250 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
17260 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
17270 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
17280 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
17290 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
172a0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
172b0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
172c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
172d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
172e0 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
172f0 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
17300 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
17310 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74   {F12807} The st
17320 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
17330 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
17340 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
17350 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
17360 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
17370 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
17380 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
17390 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
173a0 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {F12808} Calls t
173b0 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
173c0 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
173d0 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
173e0 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
173f0 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
17400 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
17410 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
17420 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
17430 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
17440 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
17450 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
17460 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
17470 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17480 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
17490 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
174a0 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72  * {F12809} Inter
174b0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
174c0 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
174d0 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
174e0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
174f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17500 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
17510 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17520 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
17530 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
17540 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
17550 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
17560 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
17570 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
17580 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17590 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
175a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
175b0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
175c0 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
175d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
175e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
175f0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
17600 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
17610 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
17620 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
17630 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
17640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17650 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
17660 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a  bject {F13000}.*
17670 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
17680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
17690 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
176a0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
176b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
176c0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
176d0 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  t single SQL sta
176e0 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a  tements.  This.*
176f0 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  * object is vari
17700 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
17710 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
17720 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22  ment" or a .** "
17730 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
17740 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
17750 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
17760 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c  t"..** .** The l
17770 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
17780 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
17790 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
177a0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
177b0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
177c0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
177d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
177e0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
177f0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
17800 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
17810 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
17820 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e   parameters usin
17830 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
17840 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
17850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e  qlite3_bind_* in
17860 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c  terfaces]..** <l
17870 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
17880 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
17890 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
178a0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
178b0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
178c0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
178d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
178e0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
178f0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
17900 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
17910 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
17920 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
17930 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
17940 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17950 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
17960 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
17970 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
17980 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
17990 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
179a0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
179b0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
179c0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
179d0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
179e0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
179f0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
17a00 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a  mits {F12760}.**
17a10 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
17a20 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
17a30 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
17a40 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
17a50 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
17a60 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
17a70 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
17a80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
17a90 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
17aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17ab0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
17ac0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
17ad0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
17ae0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17af0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
17b00 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
17b10 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
17b20 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
17b30 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
17b40 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
17b50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17b60 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
17b70 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
17b80 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75  nstruct.  The fu
17b90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17ba0 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a  he old limit..**
17bb0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c  .** If the new l
17bc0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
17bd0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
17be0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
17bf0 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69  d..** For the li
17c00 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20  mit category of 
17c10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a  SQLITE_LIMIT_XYZ
17c20 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64   there is a hard
17c30 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20   upper.** bound 
17c40 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
17c50 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65  -time C-preproce
17c60 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53  ss macro named S
17c70 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a  QLITE_MAX_XYZ..*
17c80 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
17c90 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
17ca0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
17cb0 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73  _".).** Attempts
17cc0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
17cd0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
17ce0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
17cf0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
17d00 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
17d10 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69   hard upper limi
17d20 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d  t..**.** Run tim
17d30 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
17d40 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
17d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
17d60 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
17d70 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
17d80 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
17d90 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
17da0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
17db0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
17dc0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
17dd0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
17de0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
17df0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
17e00 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
17e10 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
17e20 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
17e30 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
17e40 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
17e50 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 6a   controlled by j
17e60 61 76 61 73 63 72 69 70 74 20 61 70 70 6c 69 63  avascript applic
17e70 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
17e80 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 69 6e 74  d.** off the int
17e90 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
17ea0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
17eb0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
17ec0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
17ed0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
17ee0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
17ef0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
17f00 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
17f10 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
17f20 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
17f30 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
17f40 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
17f50 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70  attach.  Develop
17f60 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
17f70 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
17f80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17f90 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
17fa0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
17fb0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
17fc0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
17fd0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
17fe0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
17ff0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
18000 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
18010 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
18020 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
18030 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
18040 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
18050 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ce is currently 
18060 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
18070 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
18080 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61  ubject.** to cha
18090 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77  nge or removal w
180a0 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74  ithout prior not
180b0 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ice..**.** INVAR
180c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
180d0 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66  2762} A successf
180e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
180f0 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
18100 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20  ] where V is.** 
18110 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76           positiv
18120 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
18130 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20            limit 
18140 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
18150 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64  onstruct C in [d
18160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18170 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
18180 20 20 74 6f 20 74 68 65 20 6c 65 73 73 6f 72 20    to the lessor 
18190 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72  of V and the har
181a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  d upper bound on
181b0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20   the size.**    
181c0 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20        of C that 
181d0 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
181e0 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e-time..**.** {F
181f0 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73  12766} A success
18200 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
18210 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
18220 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65  )] where V is ne
18230 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
18240 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74     leaves the st
18250 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65  ate of [database
18260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75   connection] D u
18270 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
18280 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65  {F12769} A succe
18290 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
182a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
182b0 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  ,V)] returns the
182c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
182d0 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20  ue of the limit 
182e0 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
182f0 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a  onstruct C in.**
18300 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61            in [da
18310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18320 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70  n] D as it was p
18330 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
18340 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18350 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
18360 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
18370 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
18380 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
18390 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
183a0 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59   {F12790}.** KEY
183b0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
183c0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
183d0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a  ategories}.** .*
183e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
183f0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
18400 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64   aspects of a [d
18410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18420 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  on].** that can 
18430 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69  be limited in si
18440 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b  ze by calls to [
18450 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
18460 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67  ..** The meaning
18470 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
18480 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66   limits are as f
18490 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64  ollows:.**.** <d
184a0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
184b0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
184c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
184d0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
184e0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62  y.** string or b
184f0 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  lob or table row
18500 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  .<dd>.**.** <dt>
18510 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
18520 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
18530 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18540 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
18550 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
18560 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18570 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
18580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18590 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
185a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
185b0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
185c0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
185d0 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
185e0 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  CT or the maximu
185f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
18600 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
18610 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
18620 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
18630 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a   clause.</dd>.**
18640 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18650 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
18660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18670 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
18680 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
18690 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
186a0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
186b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
186c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
186d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
186e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
186f0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
18700 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
18710 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18720 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18730 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
18740 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18750 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
18760 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
18770 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
18780 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
18790 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
187a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
187b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
187c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
187d0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
187e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
187f0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
18800 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
18810 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18820 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
18830 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
18840 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18850 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
18860 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64  d databases.</dd
18870 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18880 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
18890 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
188a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
188b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
188c0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
188d0 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20  ent to the LIKE 
188e0 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61  or.** GLOB opera
188f0 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
18900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18910 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
18920 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
18930 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18940 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
18950 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18960 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
18970 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
18980 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18990 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
189a0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
189b0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
189c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
189d0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
189e0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
189f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18a00 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
18a10 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
18a20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18a30 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
18a40 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
18a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
18a60 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
18a70 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
18a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18a90 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
18aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
18ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18ac0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
18ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
18ae0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18af0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
18b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
18b10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b20 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
18b30 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
18b40 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
18b50 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
18b60 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
18b70 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
18b80 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
18b90 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
18ba0 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f  F13010}.**.** To
18bb0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
18bc0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
18bd0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
18be0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
18bf0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
18c00 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
18c10 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a  routines. .**.**
18c20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18c30 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b  ent "db" is an [
18c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18c50 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65  ion] .** obtaine
18c60 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63  d from a prior c
18c70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
18c80 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
18c90 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20  3_open_v2()].** 
18ca0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
18cb0 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73  16()]. .** The s
18cc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22  econd argument "
18cd0 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 61  zSql" is the sta
18ce0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
18cf0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
18d00 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
18d10 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
18d20 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
18d30 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
18d40 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
18d50 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 20  interfaces uses 
18d60 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65  UTF-8 and sqlite
18d70 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
18d80 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
18d90 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
18da0 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a  UTF-16. {END}.**
18db0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
18dc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
18dd0 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20  s.** than zero, 
18de0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
18df0 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
18e00 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
18e10 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69  r..** If nByte i
18e20 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
18e30 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
18e40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18e50 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20   .** bytes read 
18e60 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
18e70 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
18e80 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
18e90 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
18ea0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
18eb0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
18ec0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
18ed0 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74   or .** the nByt
18ee0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
18ef0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
18f00 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
18f10 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
18f20 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
18f30 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
18f40 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
18f50 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
18f60 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
18f70 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 79  age to be had by
18f80 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
18f90 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
18fa0 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f   .** is equal to
18fb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
18fc0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
18fd0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
18fe0 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68  uding</i> .** th
18ff0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
19000 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a   bytes.{END}.**.
19010 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  ** *pzTail is ma
19020 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
19030 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61  he first byte pa
19040 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
19050 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73  e.** first SQL s
19060 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
19070 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
19080 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20  s only compiles 
19090 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
190a0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
190b0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
190c0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
190d0 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
190e0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
190f0 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
19100 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
19110 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
19120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19130 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
19140 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
19150 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
19160 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
19170 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
19180 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c  s.** set to NULL
19190 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
191a0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
191b0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
191c0 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70  ut.** is and emp
191d0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
191e0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
191f0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
19200 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
19210 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
19220 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
19230 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
19240 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ng the.** compil
19250 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
19260 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
19270 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
19280 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
19290 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
192a0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
192b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
192c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
192d0 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  ise an .** [erro
192e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
192f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
19300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19310 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
19320 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
19330 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
19340 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
19350 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
19360 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
19370 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
19380 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
19390 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
193a0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
193b0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
193c0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
193d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
193e0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
193f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
19400 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
19410 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19420 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
19430 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19440 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
19450 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69   text. {END} Thi
19460 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
19470 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
19480 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
19490 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
194a0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
194b0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
194c0 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
194d0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
194e0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
194f0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
19500 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
19510 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
19520 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
19530 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
19540 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
19550 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
19560 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
19570 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
19580 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
19590 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
195a0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
195b0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
195c0 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
195d0 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
195e0 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
195f0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19600 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
19610 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
19620 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
19630 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19640 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
19650 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a  rror.  Calling.*
19660 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
19670 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
19680 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
19690 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
196a0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
196b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
196c0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
196d0 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
196e0 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
196f0 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
19700 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
19710 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f  urn. {END}.** </
19720 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
19730 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
19740 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
19750 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19760 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
19770 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
19780 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
19790 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
197a0 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68  r codes]. .** Th
197b0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
197c0 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
197d0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
197e0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
197f0 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
19800 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
19810 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
19820 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
19830 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
19840 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
19850 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
19860 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
19870 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
19880 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
19890 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
198a0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
198b0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
198c0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
198d0 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
198e0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
198f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
19900 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
19910 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
19920 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
19930 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
19940 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
19950 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
19960 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
19970 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
19980 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
19990 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
199a0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
199b0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
199c0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  TF-8..**.** {F13
199d0 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
199e0 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
199f0 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
19a00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19a10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19a20 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
19a30 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
19a40 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
19a50 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
19a60 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
19a70 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
19a80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19a90 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  er..**.** {F1301
19aa0 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
19ab0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
19ac0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19ad0 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
19ae0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
19af0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
19b00 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
19b10 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78  ro, then SQL tex
19b20 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
19b30 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
19b40 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
19b50 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
19b60 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
19b70 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
19b80 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
19b90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19ba0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
19bb0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
19bc0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
19bd0 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
19be0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
19bf0 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
19c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
19c10 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
19c20 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
19c30 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
19c40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
19c50 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
19c60 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
19c70 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
19c80 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
19c90 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19ca0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
19cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
19cc0 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
19cd0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
19ce0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
19cf0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
19d00 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
19d10 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
19d20 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
19d30 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
19d40 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
19d50 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
19d60 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
19d70 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
19d80 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
19d90 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
19da0 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
19db0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
19dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19dd0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
19de0 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
19df0 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
19e00 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
19e10 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
19e20 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
19e30 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
19e40 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
19e50 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
19e60 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20  ter to NULL.**  
19e70 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20          if zSql 
19e80 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
19e90 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
19ea0 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
19eb0 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ts. .**.** {F130
19ec0 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
19ed0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
19ee0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
19ef0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
19f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
19f10 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
19f20 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
19f30 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
19f40 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
19f50 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
19f60 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
19f70 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
19f80 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
19f90 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
19fa0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
19fb0 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
19fc0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
19fd0 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20  QLITE_OK]).**   
19fe0 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20         it first 
19ff0 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20  sets *ppStmt to 
1a000 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1a010 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1a020 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a030 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a040 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a050 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a060 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a070 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1a080 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a090 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a0a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a0b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a0c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a0d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a0e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a0f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a100 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a110 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a120 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a130 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a140 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a160 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1a170 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1a180 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1a190 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a1a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1a1b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1a1c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1a1d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a1e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a1f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a200 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a210 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a220 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a230 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a240 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a250 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1a260 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a270 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a280 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a290 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1a2a0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1a2b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1a2c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1a2d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a2e0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1a2f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1a300 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1a310 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1a320 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1a330 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1a340 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1a350 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1a360 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1a370 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1a380 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1a390 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1a3a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1a3b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1a3c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1a3d0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1a3e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1a3f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1a400 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1a410 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1a420 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1a430 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1a440 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1a450 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1a460 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1a470 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1a480 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1a490 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1a4a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1a4b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1a4c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1a4d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1a4e0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1a4f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1a500 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1a510 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1a520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a  ../*.** CAPIREF:
1a530 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1a540 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30  ement SQL {F1310
1a550 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1a560 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20  tereface can be 
1a570 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1a580 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1a590 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1a5a0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1a5b0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1a5c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1a5d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a5e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31  S:.**.** {F13101
1a5f0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1a600 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1a610 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1a620 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1a630 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1a640 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1a650 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1a660 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a670 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a680 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a6a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a6b0 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  v2()],.**       
1a6c0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
1a6d0 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e  _sql()] function
1a6e0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1a6f0 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20  er to a.**      
1a700 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1a710 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ted string conta
1a720 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65  ining a UTF-8 re
1a730 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ndering.**      
1a740 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69      of the origi
1a750 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
1a760 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32  t..**.** {F13102
1a770 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1a780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1a790 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1a7a0 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1a7b0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1a7c0 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1a7d0 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1a7e0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a7f0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a800 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
1a810 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a820 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1a830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a840 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1a850 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1a860 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1a870 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33  r..**.** {F13103
1a880 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1a890 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a8a0 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1a8b0 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1a8c0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1a8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1a8e0 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1a8f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1a900 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1a910 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1a920 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1a930 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1a940 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d  CAPI3REF:  Dynam
1a950 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1a960 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30  ue Object  {F150
1a970 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1a980 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1a990 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1a9a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a9b0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1a9c0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1a9d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a9e0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1a9f0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1aa00 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1aa10 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1aa20 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ble..** SQLite u
1aa30 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1aa40 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
1aa50 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a  s it stores.  .*
1aa60 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  * Values stored 
1aa70 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1aa80 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a   objects can be.
1aa90 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
1aaa0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1aab0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1aac0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1aad0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1aae0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1aaf0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1ab00 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1ab10 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1ab20 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1ab30 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1ab40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1ab50 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1ab60 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1ab70 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1ab80 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1ab90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1aba0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1abb0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1abc0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1abd0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1abe0 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68  cifies .** wheth
1abf0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1ac00 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1ac10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1ac20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1ac30 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1ac40 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1ac50 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1ac60 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1ac70 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1ac80 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1ac90 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1aca0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1acb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1acc0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1acd0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1ace0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1acf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1ad00 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1ad10 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1ad20 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1ad30 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ith SQLITE_THREA
1ad40 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68  DSAFE=0 and with
1ad50 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1ad60 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1ad70 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  g 0).** then the
1ad80 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1ad90 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
1ada0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1adb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1adc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1add0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a  and they can be.
1ade0 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  ** used intercha
1adf0 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72  ngable.  However
1ae00 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  , for maximum co
1ae10 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1ae20 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e  t.** is recommen
1ae30 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1ae40 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64  tions make the d
1ae50 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1ae60 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72  en.** between pr
1ae70 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1ae80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ae90 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
1aea0 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72  en if.** they ar
1aeb0 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65  e single threade
1aec0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1aed0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1aee0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1aef0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1af00 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1af10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
1af20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1af30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1af40 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1af50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
1af60 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
1af70 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
1af80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
1af90 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
1afa0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
1afb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1afc0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
1afd0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
1afe0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
1aff0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
1b000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1b010 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65  ue()].  All othe
1b020 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
1b030 74 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 33  that use sqlite3
1b040 5f 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 70  _value require p
1b050 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1b060 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1b070 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1b080 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1b090 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1b0a0 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74  3REF:  SQL Funct
1b0b0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
1b0c0 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a  ct {F16001}.**.*
1b0d0 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1b0e0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1b0f0 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1b100 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1b110 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1b120 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f  xt object.  A po
1b130 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
1b140 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f  te3_context.** o
1b150 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20  bject is always 
1b160 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b170 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  to application-d
1b180 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1b190 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ions..*/.typedef
1b1a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1b1b0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1b1c0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1b1d0 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
1b1e0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1b1f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1b200 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
1b210 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1b220 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1b230 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b240 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61  )] and its.** va
1b250 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73  riants, literals
1b260 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20   may be replace 
1b270 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
1b280 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73  n one.** of thes
1b290 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1b2a0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1b2b0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1b2c0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1b2d0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1b2e0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1b2f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1b300 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1b310 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1b320 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1b330 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61  al,.** VVV alpha
1b340 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1b350 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  er name..** The 
1b360 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
1b370 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1b380 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1b390 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a  rameter names".*
1b3a0 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  * or "SQL parame
1b3b0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1b3c0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1b3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1b3e0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1b3f0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1b400 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b410 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1b420 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1b430 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20   always.** is a 
1b440 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1b450 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1b460 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1b470 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1b480 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b490 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68  its variants. Th
1b4a0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
1b4b0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1b4c0 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
1b4d0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68  er to be set. Th
1b4e0 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
1b4f0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1b500 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1b510 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1b520 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1b530 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1b540 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1b550 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1b560 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1b570 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1b580 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1b590 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65  ce. .** The inde
1b5a0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
1b5b0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
1b5c0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
1b5d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
1b5e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1b5f0 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
1b600 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1b610 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1b620 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1b630 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1b640 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1b650 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1b660 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
1b670 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
1b680 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
1b690 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
1b6a0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1b6b0 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1b6c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1b6d0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1b6e0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1b6f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1b700 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
1b710 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1b720 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1b730 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1b740 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1b750 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1b760 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1b770 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1b780 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1b790 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68  tes</u>.** in th
1b7a0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1b7b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1b7c0 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68  cters. .** If th
1b7d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b7e0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1b7f0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1b800 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
1b810 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1b820 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1b830 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1b840 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
1b850 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1b860 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1b870 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1b880 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1b890 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1b8a0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1b8b0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1b8c0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1b8d0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1b8e0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1b8f0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
1b900 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b910 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1b920 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1b930 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1b940 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1b950 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1b960 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1b970 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1b980 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1b990 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1b9a0 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
1b9b0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1b9c0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1b9d0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1b9e0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1b9f0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1ba00 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1ba10 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1ba20 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1ba30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1ba40 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1ba50 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
1ba60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1ba70 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1ba80 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1ba90 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1baa0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1bab0 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  eros.  A zeroblo
1bac0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1bad0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1bae0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1baf0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73  ger to hold it s
1bb00 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1bb10 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1bb20 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1bb30 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1bb40 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f  erve as place-ho
1bb50 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1bb60 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1bb70 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1bb80 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1bb90 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1bba0 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1bbb0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1bbc0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1bbd0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1bbe0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1bbf0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1bc00 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1bc10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1bc20 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1bc30 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1bc40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1bc50 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1bc60 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1bc70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1bc80 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1bc90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1bca0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1bcb0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1bcc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1bcd0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1bce0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1bcf0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1bd00 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1bd10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1bd20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1bd30 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1bd40 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1bd50 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1bd60 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1bd70 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1bd80 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1bd90 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1bda0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1bdb0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1bdc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1bdd0 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
1bde0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1bdf0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1be00 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1be10 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1be20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1be30 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1be40 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1be50 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1be60 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1be70 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1be80 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1be90 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1bea0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1beb0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1bec0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1bed0 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1bee0 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1bef0 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1bf00 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1bf10 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1bf20 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1bf30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1bf40 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1bf50 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1bf60 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1bf70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bf80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1bf90 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1bfa0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1bfb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1bfc0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1bfd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bfe0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1bff0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1c000 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36  S:.**.** {F13506
1c010 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1c020 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61  repare | SQL sta
1c030 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
1c040 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20   recognizes.**  
1c050 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f          tokens o
1c060 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c  f the forms "?",
1c070 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
1c080 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
1c090 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VV".**          
1c0a0 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
1c0b0 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20  s, where NNN is 
1c0c0 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1c0d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
1c0e0 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61          digits a
1c0f0 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
1c100 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1c110 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
1c120 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75           alphanu
1c130 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73  meric characters
1c140 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
1c150 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a  lly followed by.
1c160 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74  **          a st
1c170 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1c180 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
1c190 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
1c1a0 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
1c1b0 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69  * {F13509} The i
1c1c0 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
1c1d0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1c1e0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1c1f0 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {F13512} The ind
1c200 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
1c210 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1c220 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1c230 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
1c240 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
1c250 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1c260 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
1c270 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1c280 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
1c290 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1c2a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ter..**.** {F135
1c2b0 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
1c2c0 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
1c2d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1c2e0 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
1c2f0 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20  ** {F13518} The 
1c300 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
1c310 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
1c320 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
1c330 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
1c340 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
1c350 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
1c360 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20  most occurances 
1c370 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1c380 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1c390 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1c3a0 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1c3b0 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1c3c0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1c3d0 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1c3e0 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1c3f0 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63   first occurranc
1c400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1c410 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1c420 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1c430 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1c440 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1c450 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1c460 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1c470 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1c480 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1c490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1c4a0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1c4b0 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1c4c0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1c4d0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1c4e0 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1c4f0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1c500 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1c510 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1c520 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1c530 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c540 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c550 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1c560 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1c570 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1c580 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1c590 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1c5a0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1c5b0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1c5c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1c5d0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1c5e0 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1c5f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c600 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c610 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1c620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c630 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1c640 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1c650 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1c660 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1c670 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1c680 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1c690 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c6a0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1c6b0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1c6c0 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1c6d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c6e0 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1c6f0 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1c700 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c710 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1c720 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1c730 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1c740 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1c750 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1c760 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c770 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c780 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c790 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1c7a0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1c7b0 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1c7c0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1c7d0 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1c7e0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1c7f0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1c800 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1c810 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c820 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1c830 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1c840 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c850 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c860 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c870 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1c880 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1c890 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1c8a0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1c8b0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1c8c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1c8d0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1c8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1c8f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1c900 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c910 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1c920 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1c930 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c940 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1c950 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1c960 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1c970 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1c980 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1c990 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1c9a0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1c9b0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1c9c0 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1c9d0 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1c9e0 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1c9f0 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1ca00 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1ca10 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1ca20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1ca30 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1ca40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1ca50 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1ca60 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1ca70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1ca80 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1ca90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1caa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1cab0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1cac0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1cad0 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1cae0 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1caf0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1cb00 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1cb10 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1cb20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1cb30 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1cb40 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1cb50 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1cb60 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1cb70 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1cb80 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1cb90 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cba0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1cbb0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1cbc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1cbd0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1cbe0 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1cbf0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1cc00 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1cc10 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1cc20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1cc30 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1cc40 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1cc50 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1cc60 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1cc70 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1cc80 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1cc90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1cca0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1ccb0 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1ccc0 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1ccd0 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1cce0 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1ccf0 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1cd00 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1cd10 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
1cd20 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1cd30 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
1cd40 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
1cd50 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
1cd60 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
1cd70 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
1cd80 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1cd90 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
1cda0 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
1cdb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1cdc0 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
1cdd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1cde0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1cdf0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1ce00 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1ce10 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1ce20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1ce30 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1ce40 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1ce50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ce60 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1ce70 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1ce80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ce90 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1cea0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1ceb0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1cec0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1ced0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1cee0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1cef0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1cf00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1cf10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1cf20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1cf30 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1cf40 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1cf50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1cf60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1cf70 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cf80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cf90 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1cfa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cfb0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1cfc0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1cfd0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1cfe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cff0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1d000 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1d010 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1d020 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1d030 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1d040 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1d050 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1d060 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1d070 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1d080 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1d090 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1d0a0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1d0b0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1d0c0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1d0d0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1d0e0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1d0f0 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1d100 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1d110 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1d120 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1d130 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1d140 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1d150 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
1d160 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1d170 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1d180 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1d190 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46   parameter..** F
1d1a0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1d1b0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1d1c0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1d1d0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  o the number of.
1d1e0 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  ** unique parame
1d1f0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1d200 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1d210 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65   are used, there
1d220 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20   may.** be gaps 
1d230 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1d240 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d250 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d260 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d280 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d290 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1d2a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d2b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1d2c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1d2d0 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54  **.** {F13601} T
1d2e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1d2f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1d300 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
1d310 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d320 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
1d330 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
1d340 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
1d350 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1d360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d370 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a  t] S, or 0 if S.
1d380 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
1d390 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
1d3a0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
1d3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d3c0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1d3d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1d3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1d3f0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1d400 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
1d410 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1d420 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1d430 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1d440 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53  of the n-th.** S
1d450 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1d460 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1d470 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1d480 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1d490 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1d4a0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1d4b0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1d4c0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1d4d0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1d4e0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1d4f0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1d500 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1d510 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1d520 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1d530 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1d540 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1d550 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1d560 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1d570 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1d580 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1d590 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1d5a0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1d5b0 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  o name..**.** Th
1d5c0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1d5d0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1d5e0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1d5f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
1d600 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
1d610 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
1d620 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
1d630 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
1d640 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
1d650 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
1d660 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
1d670 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55   always in the U
1d680 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1d690 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1d6a0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1d6b0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1d6c0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1d6d0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1d6e0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1d6f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d700 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1d710 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1d720 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1d730 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1d740 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1d750 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1d760 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1d770 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d780 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1d790 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1d7a0 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20  ** {F13621} The 
1d7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1d7c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
1d7d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1d7e0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
1d7f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1d800 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
1d810 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
1d820 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
1d830 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1d840 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
1d850 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
1d860 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
1d870 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
1d880 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
1d890 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
1d8a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
1d8b0 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
1d8c0 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
1d8d0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
1d8e0 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
1d8f0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1d900 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1d910 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d920 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1d930 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1d940 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1d950 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33   Given Name {F13
1d960 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  640}.**.** Retur
1d970 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1d980 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1d990 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1d9a0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
1d9b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1d9c0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1d9d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1d9e0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1d9f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1da00 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1da10 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
1da20 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1da30 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1da40 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
1da50 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1da60 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1da70 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1da80 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1da90 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1daa0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1dab0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1dac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dad0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1dae0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1daf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1db00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1db10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1db20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1db30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1db40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1db50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1db60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1db70 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68  *.** {F13641} Th
1db80 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1db90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1dba0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1dbb0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
1dbc0 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66      the index of
1dbd0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1dbe0 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
1dbf0 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
1dc00 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20     S whose name 
1dc10 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d  matches the UTF-
1dc20 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30  8 string N, or 0
1dc30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20   if there is.** 
1dc40 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63           no matc
1dc50 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  h..*/.int sqlite
1dc60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dc70 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
1dc80 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
1dc90 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
1dca0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
1dcb0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
1dcc0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
1dcd0 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a  ement {F13660}.*
1dce0 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
1dcf0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
1dd00 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
1dd10 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
1dd20 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20  ot.** reset the 
1dd30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1dd40 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
1dd50 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  n a .** [prepare
1dd60 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55  d statement].  U
1dd70 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
1dd80 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20  to.** reset all 
1dd90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1dda0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
1ddb0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1ddc0 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {F13661} The [s
1ddd0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
1dde0 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
1ddf0 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a  ace resets all.*
1de00 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70  *          SQL p
1de10 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1de20 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73  s in [prepared s
1de30 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
1de40 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
1de50 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1de60 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
1de70 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
1de80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1de90 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
1dea0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
1deb0 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a  lt Set {F13710}.
1dec0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
1ded0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1dee0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
1def0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
1df00 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
1df10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
1df20 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1df30 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d  rns 0.** if pStm
1df40 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74  t is an SQL stat
1df50 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
1df60 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
1df70 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65  (for .** example
1df80 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a   an UPDATE)..**.
1df90 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dfa0 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68  *.** {F13711} Th
1dfb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1dfc0 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  n_count(S)] inte
1dfd0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1dfe0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
1dff0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20          columns 
1e000 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1e010 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74  t generated by t
1e020 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1e030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e040 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53  nt] S, or 0 if S
1e050 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61   does not genera
1e060 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
1e070 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a   result set..*/.
1e080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1e090 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1e0a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1e0b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e0c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1e0d0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
1e0e0 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3720}.**.** Thes
1e0f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1e100 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
1e110 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
1e120 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
1e130 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e140 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
1e150 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
1e160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e170 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
1e180 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e190 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
1e1a0 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e  nated UTF8 strin
1e1b0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
1e1c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1e1d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e1e0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1e1f0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36  minated.** UTF16
1e200 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
1e210 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1e220 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1e230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1e240 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
1e250 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1e260 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  t..** The second
1e270 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1e280 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  e column number.
1e290 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
1e2a0 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d  column is.** num
1e2b0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
1e2c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1e2d0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
1e2e0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
1e2f0 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
1e300 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
1e310 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
1e320 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1e330 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
1e340 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74   next call sqlit
1e350 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1e360 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1e370 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f  mn_name16().** o
1e380 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
1e390 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
1e3a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
1e3b0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
1e3c0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
1e3d0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
1e3e0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
1e3f0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
1e400 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
1e410 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
1e420 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1e430 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1e440 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
1e450 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
1e460 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
1e470 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
1e480 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
1e490 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
1e4a0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
1e4b0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
1e4c0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
1e4d0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
1e4e0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
1e4f0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
1e500 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
1e510 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
1e520 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
1e530 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e540 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75  ** {F13721} A su
1e550 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1e560 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
1e570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e580 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
1e590 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
1e5a0 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  rns the name.** 
1e5b0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1e5c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
1e5d0 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d  e 0 is the left-
1e5e0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
1e5f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e600 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
1e610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e620 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20  nt] S as a.**   
1e630 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1e640 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1e650 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ing..**.** {F137
1e660 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  23} A successful
1e670 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
1e680 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1e690 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a  mn_name16(S,N)].
1e6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1e6b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1e6c0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1e6d0 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f     of the Nth co
1e6e0 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
1e6f0 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   the left-most c
1e700 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a  olumn) for the.*
1e710 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
1e720 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
1e730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1e740 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  as a.**         
1e750 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e760 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1e770 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1e780 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
1e790 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  F13724} The [sql
1e7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1e7b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e7c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1e7d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1e7e0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1e7f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
1e800 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
1e810 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
1e820 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1e830 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1e840 74 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74  there normal ret
1e850 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
1e860 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74  ** {F13725} If t
1e870 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1e880 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
1e890 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
1e8a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1e8b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1e8c0 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
1e8d0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
1e8e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
1e8f0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1e900 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e910 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36  ..** .** {F13726
1e920 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1e930 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1e940 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e950 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ,N)] and.**     
1e960 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1e970 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
1e980 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  ] are valid unti
1e990 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20  l the next.**   
1e9a0 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65         call to e
1e9b0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69  ither routine wi
1e9c0 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e  th the same S an
1e9d0 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  d N parameters.*
1e9e0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
1e9f0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  til [sqlite3_fin
1ea00 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
1ea10 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  led..**.** {F137
1ea20 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c  27} When a resul
1ea30 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53  t column of a [S
1ea40 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1ea50 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
1ea60 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75        an AS clau
1ea70 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  se, the name of 
1ea80 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  that column is t
1ea90 68 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a  he indentifier.*
1eaa0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
1eab0 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41  e right of the A
1eac0 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f  S keyword..*/.co
1ead0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1eae0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1eaf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1eb00 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1eb10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1eb20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1eb30 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1eb40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1eb50 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1eb60 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1eb70 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13740}.**.** T
1eb80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1eb90 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1eba0 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1ebb0 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1ebc0 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1ebd0 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1ebe0 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  lt of a SELECT s
1ebf0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
1ec00 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
1ec10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1ec20 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
1ec30 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
1ec40 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
1ec50 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36   a UTF8 or UTF16
1ec60 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
1ec70 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
1ec80 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
1ec90 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
1eca0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
1ecb0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
1ecc0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
1ecd0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
1ece0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1ecf0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
1ed00 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1ed10 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
1ed20 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65  ntil.** the [pre
1ed30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1ed40 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73   is destroyed us
1ed50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ed60 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
1ed70 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
1ed80 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
1ed90 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
1eda0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
1edb0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
1edc0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
1edd0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
1ede0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
1edf0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
1ee00 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
1ee10 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
1ee20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1ee30 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
1ee40 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
1ee50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ee60 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
1ee70 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
1ee80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
1ee90 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
1eea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1eeb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1eec0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1eed0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1eee0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1eef0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1ef00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1ef10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1ef20 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f   expression.** o
1ef30 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  r subquery and i
1ef40 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1ef50 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1ef60 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1ef70 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c  s.** return NULL
1ef80 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1ef90 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1efa0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1efb0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
1efc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1efd0 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1efe0 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20   return the .** 
1eff0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
1f000 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
1f010 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1f020 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
1f030 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20  t.** column was 
1f040 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
1f050 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
1f060 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
1f070 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
1f080 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
1f090 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
1f0a0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
1f0b0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
1f0c0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
1f0d0 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  8. {END}.**.** T
1f0e0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
1f0f0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1f100 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1f110 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1f120 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  e .** SQLITE_ENA
1f130 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1f140 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
1f150 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
1f160 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a  .**.** {U13751}.
1f170 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
1f180 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
1f190 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
1f1a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
1f1b0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
1f1c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f1d0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
1f1e0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1f1f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1f200 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
1f210 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
1f220 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1f230 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
1f240 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1f250 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1f260 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1f270 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1f280 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
1f290 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1f2a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1f2b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f2d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f2e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f2f0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f300 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f310 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f320 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f330 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f340 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f350 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f360 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f370 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f380 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f390 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f3a0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32       .** {F13742
1f3b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1f3c0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1f3d0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
1f3e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1f3f0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1f400 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
1f410 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
1f420 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1f430 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1f440 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1f450 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f460 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f470 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f490 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f4a0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f4b0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f4c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f4d0 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f4e0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f4f0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f500 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f510 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f520 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f530 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f540 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d      .** {F13743}
1f550 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f560 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
1f570 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1f580 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
1f590 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
1f5a0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1f5b0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
1f5c0 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63   table from whic
1f5d0 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1f5e0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1f5f0 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1f600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1f610 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1f620 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1f630 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1f640 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1f650 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1f660 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1f670 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1f680 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1f690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1f6a0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1f6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1f6c0 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {F13744} The [sq
1f6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1f6e0 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
1f6f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1f700 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1f710 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
1f720 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1f730 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
1f740 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
1f750 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
1f760 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f770 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f780 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f7a0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f7b0 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f7c0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f7d0 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f7e0 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f7f0 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f800 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f810 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f820 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f830 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f840 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f850 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35       .** {F13745
1f860 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1f870 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1f880 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
1f890 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1f8a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f8b0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1f8c0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1f8d0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1f8e0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f900 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f920 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f930 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f940 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f950 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f960 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f970 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f980 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f990 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f9a0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f9b0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f9c0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f9d0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36       .** {F13746
1f9e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1f9f0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1fa00 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
1fa10 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
1fa20 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
1fa30 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
1fa40 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
1fa50 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1fa60 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
1fa70 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1fa80 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1fa90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1faa0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1fab0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1fac0 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1fad0 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1fae0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1faf0 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1fb00 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1fb10 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1fb20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1fb30 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1fb40 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1fb50 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1fb60 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1fb70 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1fb80 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  8} The return va
1fb90 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  lues from.**    
1fba0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
1fbb0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1fbc0 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  ame|column metad
1fbd0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
1fbe0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
1fbf0 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20  valid.**        
1fc00 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69    for the lifeti
1fc10 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  me of the [prepa
1fc20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1fc30 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
1fc40 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  til the encoding
1fc50 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61   is changed by a
1fc60 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a  nother metadata.
1fc70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1fc80 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74  rface call for t
1fc90 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64  he same prepared
1fca0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
1fcb0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  olumn..**.** LIM
1fcc0 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
1fcd0 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20  {U13751} If two 
1fce0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1fcf0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1fd00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1fd10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1fd20 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d  abase_name|colum
1fd30 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
1fd40 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
1fd50 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65     the same [pre
1fd60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fd70 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
1fd80 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  mn.**          a
1fd90 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1fda0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1fdb0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1fdc0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1fdd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1fde0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
1fdf0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1fe00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1fe10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1fe20 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
1fe30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fe40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1fe50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1fe60 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1fe70 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1fe80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1fe90 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
1fea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1feb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1fec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1fed0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
1fee0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1fef0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1ff00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1ff10 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1ff20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1ff30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1ff40 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
1ff50 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
1ff60 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a  t {F13760}.**.**
1ff70 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1ff80 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
1ff90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1ffa0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
1ffb0 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43  ement is a SELEC
1ffc0 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  T statement and 
1ffd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1ffe0 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e  f the .** return
1fff0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
20000 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
20010 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
20020 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
20030 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
20040 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
20050 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
20060 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
20070 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
20080 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
20090 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
200a0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
200b0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
200c0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
200d0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
200e0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
200f0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
20100 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
20110 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46  ed.  {END} .** F
20120 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74  or example, in t
20130 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
20140 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
20150 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
20160 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64  IANT);.**.** And
20170 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
20180 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
20190 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
201a0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
201b0 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74  t1;.**.** Then t
201c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
201d0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
201e0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
201f0 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  r the second.** 
20200 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
20210 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
20220 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20230 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20240 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a  lumn.** (i==0)..
20250 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
20260 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
20270 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a  me typing.  So j
20280 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
20290 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
202a0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
202b0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
202c0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
202d0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
202e0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
202f0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
20300 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
20310 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
20320 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
20330 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
20340 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
20350 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61  c.  Type.** is a
20360 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
20370 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
20380 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
20390 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
203a0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
203b0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  values..**.** IN
203c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
203d0 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63  {F13761}  A succ
203e0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
203f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20400 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a  ecltype(S,N)].**
20410 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
20420 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
20430 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
20440 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
20450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
20460 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
20470 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
20480 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
20490 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
204a0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
204b0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
204c0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
204d0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
204e0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
204f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20500 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36   S..**.** {F1376
20510 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
20520 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20530 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
20540 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
20550 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
20560 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
20570 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
20580 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
20590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
205a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
205b0 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
205c0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
205d0 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
205e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
205f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
20600 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
20610 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
20620 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
20630 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
20640 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
20650 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49  *.** {F13763}  I
20660 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
20670 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
20680 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
20690 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
206a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
206b0 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61  olumns in [prepa
206c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
206d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
206e0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
206f0 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78  mn of S is an ex
20700 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
20710 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20  uery rather.**  
20720 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20           than a 
20730 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20  table column or 
20740 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
20750 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a  cation failure.*
20760 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
20770 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69  rs during encodi
20780 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20  ng conversions, 
20790 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
207a0 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69    calls to [sqli
207b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
207c0 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ype(S,N)] or.** 
207d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
207e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
207f0 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72  pe16(S,N)] retur
20800 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74  n NULL..*/.const
20810 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20820 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
20830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
20840 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
20850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20860 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
20870 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20880 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20   .** CAPI3REF:  
20890 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
208a0 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30  Statement {F1320
208b0 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0}.**.** After a
208c0 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
208d0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
208e0 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20  prepared with a 
208f0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65  call.** to eithe
20900 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20910 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
20920 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20930 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f  2()] or to one o
20940 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20  f.** the legacy 
20950 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
20960 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
20970 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20980 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  re16()],.** then
20990 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   this function m
209a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
209b0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
209c0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
209d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  .** statement..*
209e0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
209f0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
20a00 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33   of this sqlite3
20a10 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
20a20 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
20a30 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
20a40 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
20a50 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
20a60 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
20a70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20a80 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20a90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20aa0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
20ab0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
20ac0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
20ad0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
20ae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20af0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
20b00 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
20b10 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
20b20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20b30 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
20b40 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
20b50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
20b60 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
20b70 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
20b80 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
20b90 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
20ba0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
20bb0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
20bc0 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b  ITE_BUSY], .** [
20bd0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
20be0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
20bf0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
20c00 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
20c10 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
20c20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
20c30 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51  of the other [SQ
20c40 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
20c50 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51   code].** or [SQ
20c60 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
20c70 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
20c80 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65  t code] might be
20c90 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
20ca0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
20cb0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
20cc0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
20cd0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
20ce0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
20cf0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
20d00 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
20d10 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
20d20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
20d30 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72  s a COMMIT.** or
20d40 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
20d50 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
20d60 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
20d70 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
20d80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
20d90 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
20da0 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d  nt is not a COMM
20db0 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  IT and occurs wi
20dc0 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
20dd0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
20de0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
20df0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
20e00 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
20e10 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
20e20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
20e30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20e40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
20e50 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
20e60 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
20e70 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
20e80 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
20e90 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
20ea0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
20eb0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
20ec0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
20ed0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20ee0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
20ef0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
20f00 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
20f10 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
20f20 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
20f30 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
20f40 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
20f50 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a  y data, then .**
20f60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73   [SQLITE_ROW] is
20f70 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
20f80 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
20f90 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a   data is ready.*
20fa0 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  * for processing
20fb0 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
20fc0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
20fd0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
20fe0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
20ff0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f  _column_int | co
21000 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
21010 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
21020 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
21030 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
21040 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
21050 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a  ow of data..** .
21060 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
21070 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
21080 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
21090 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
210a0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
210b0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
210c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
210d0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
210e0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
210f0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
21100 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
21110 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
21120 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
21130 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
21140 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
21150 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
21160 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
21170 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c  example:.** [SQL
21180 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
21190 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
211a0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
211b0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
211c0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
211d0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
211e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
211f0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
21200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21210 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
21220 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
21230 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
21240 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
21250 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
21260 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
21270 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
21280 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
21290 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
212a0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
212b0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
212c0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
212d0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
212e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
212f0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
21300 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
21310 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
21320 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
21330 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a  one that had .**
21340 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
21350 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
21360 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
21370 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
21380 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
21390 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
213a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
213b0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
213c0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
213d0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
213e0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
213f0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n time..**.** <b
21400 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
21410 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49   Alert:</b>.** I
21420 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
21430 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20  erface, .** the 
21440 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41  sqlite3_step() A
21450 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
21460 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
21470 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49  r code,.** [SQLI
21480 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
21490 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f  wing any error o
214a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
214b0 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b  E_BUSY].** and [
214c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
214d0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b   You must call [
214e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
214f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21500 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
21510 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
21520 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63   of the specific
21530 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
21540 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
21550 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
21560 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
21570 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
21580 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
21590 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
215a0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
215b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
215c0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
215d0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
215e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
215f0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
21600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21610 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
21620 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21630 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
21640 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
21650 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
21660 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
21670 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
21680 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63  he .** more spec
21690 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
216a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
216b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
216c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
216d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
216e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
216f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
21700 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21710 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20  **.** {F13202}  
21720 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  If [prepared sta
21730 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61  tement] S is rea
21740 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20  dy to be.**     
21750 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20        run, then 
21760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21770 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20  ] advances that 
21780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21790 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nt.**           
217a0 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74  until to complet
217b0 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20  ion or until it 
217c0 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  is ready to retu
217d0 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20  rn another.**   
217e0 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74          row of t
217f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72  he result set or
21800 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72   an interrupt or
21810 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
21820 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  occurs..**.** {F
21830 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63  15304}  When a c
21840 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21850 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20  step(S)] causes 
21860 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
21870 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
21880 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20  ement] S to run 
21890 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a  to completion,.*
218a0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
218b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
218c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
218d0 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20  **.** {F15306}  
218e0 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
218f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21900 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69   stops because i
21910 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20  t is ready.**   
21920 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72          to retur
21930 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
21940 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c   the result set,
21950 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20   it returns.**  
21960 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
21970 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  _ROW]..**.** {F1
21980 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c  5308}  If a call
21990 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
219a0 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73  p(S)] encounters
219b0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
219c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
219d0 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f  upt|interrupt] o
219e0 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
219f0 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
21a00 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61   it returns an a
21a10 70 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72  ppropraite error
21a20 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f   code that is no
21a30 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20  t one of.**     
21a40 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
21a50 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
21a60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
21a70 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30  ]..**.** {F15310
21a80 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  }  If an [sqlite
21a90 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65  3_interrupt|inte
21aa0 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69  rrupt] or run-ti
21ab0 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
21ac0 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
21ad0 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
21ae0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
21af0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
21b00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21b10 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
21b20 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
21b30 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
21b40 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
21b50 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
21b60 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
21b70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21b80 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
21b90 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  on returns eithe
21ba0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
21bb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b  SQLITE_ERROR], [
21bc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72  SQLITE_BUSY], or
21bd0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
21be0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21bf0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
21c00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21c10 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
21c20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
21c30 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30  sult set {F13770
21c40 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
21c50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
21c60 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
21c70 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
21c80 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
21c90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21ca0 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65  * {F13771}  Afte
21cb0 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
21cc0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
21cd0 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  at returns.**   
21ce0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
21cf0 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74  ROW], the [sqlit
21d00 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
21d10 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20  ] routine.**    
21d20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75         will retu
21d30 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
21d40 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  e as the.**     
21d50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
21d60 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
21d70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
21d80 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20  {F13772}  After 
21d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21da0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61  ] has returned a
21db0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
21dc0 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
21dd0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
21de0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
21df0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65  _step(S)] has be
21e00 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  en .**          
21e10 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
21e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21e30 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  nt] for.**      
21e40 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74       the first t
21e50 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
21e60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21e70 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20  e|prepared].**  
21e80 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
21e90 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74  ite3_reset|reset
21ea0 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ], the [sqlite3_
21eb0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a  data_count(S)].*
21ec0 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  *           rout
21ed0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
21ee0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21ef0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
21f00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
21f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21f20 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
21f30 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35  atatypes {F10265
21f40 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
21f50 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
21f60 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76   {F10266}Every v
21f70 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
21f80 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
21f90 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
21fa0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
21fb0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
21fc0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
21fd0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
21fe0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
21ff0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
22000 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
22010 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
22020 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  L.** </ul> {END}
22030 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
22040 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
22050 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
22060 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
22070 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
22080 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
22090 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
220a0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
220b0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
220c0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
220d0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
220e0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
220f0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
22100 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22110 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
22120 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
22130 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e  e SQLITE3_TEXT n
22140 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
22150 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
22160 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
22170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
22180 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
22190 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
221a0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
221b0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
221c0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
221d0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
221e0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
221f0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
22200 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
22210 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
22220 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
22230 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73  API3REF: Results
22240 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
22250 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a  uery {F13800}.**
22260 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22270 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
22280 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69  ult set query" i
22290 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
222a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
222b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
222c0 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e  n about.** a sin
222d0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
222e0 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74  e current result
222f0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
22300 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61    In every.** ca
22310 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
22320 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
22330 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70  er to the .** [p
22340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22350 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
22360 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74  .** evaluated (t
22370 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
22380 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75  *] that was retu
22390 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  rned from .** [s
223a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
223b0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
223c0 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64  ts variants) and
223d0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61  .** the second a
223e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
223f0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
22400 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
22410 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f  ormation .** sho
22420 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
22430 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
22440 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
22450 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20  sult set.** has 
22460 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a  an index of 0..*
22470 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
22480 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
22490 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
224a0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
224b0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68   or if the.** th
224c0 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  e column index i
224d0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
224e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
224f0 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65  defined. .** The
22500 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
22510 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
22520 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
22530 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
22540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22550 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
22560 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
22570 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
22580 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
22590 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
225a0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
225b0 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  l subsequently..
225c0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
225d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
225e0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
225f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22600 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
22610 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
22620 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
22630 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
22640 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
22650 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
22660 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
22670 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
22680 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
22690 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
226a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
226b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
226c0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
226d0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
226e0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
226f0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
22700 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
22710 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
22720 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22730 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  efined.  .**.** 
22740 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
22750 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
22760 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  e returns .** [S
22770 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
22780 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
22790 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
227a0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
227b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
227c0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
227d0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
227e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
227f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
22800 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
22810 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
22820 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
22830 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
22840 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
22850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22860 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
22870 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
22880 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22890 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
228a0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
228b0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
228c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
228d0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
228e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
228f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
22900 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
22910 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
22920 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
22930 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
22940 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
22950 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
22960 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
22970 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
22980 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
22990 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
229a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
229b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
229c0 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74  bytes() .** rout
229d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
229e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
229f0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
22a00 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
22a10 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
22a20 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
22a30 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
22a40 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
22a50 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
22a60 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
22a70 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
22a80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
22a90 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
22aa0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
22ab0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
22ac0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
22ad0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
22ae0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
22af0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
22b00 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
22b10 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
22b20 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
22b30 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
22b40 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
22b50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
22b60 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
22b70 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
22b80 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
22b90 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
22ba0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
22bb0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22bc0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
22bd0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
22be0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
22bf0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
22c00 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72  cters..**.** Str
22c10 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
22c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22c30 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
22c40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22c50 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
22c60 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
22c70 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
22c80 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75  nated.  The retu
22c90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
22ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22cb0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
22cc0 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73  o-length blob is
22cd0 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a   an arbitrary.**
22ce0 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62   pointer, possib
22cf0 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70  ly even a NULL p
22d00 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
22d10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22d20 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
22d30 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
22d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22d50 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
22d60 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
22d70 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
22d80 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
22d90 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
22da0 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  .  .** The zero 
22db0 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
22dc0 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
22dd0 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
22de0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
22df0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
22e00 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
22e10 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
22e20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22e30 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
22e40 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
22e50 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22e60 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
22e70 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
22e80 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
22e90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
22ea0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
22eb0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
22ec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22ed0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
22ee0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
22ef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
22f00 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
22f10 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
22f20 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
22f30 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
22f40 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ke .** [sqlite3_
22f50 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
22f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
22f70 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  t()], or [sqlite
22f80 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
22f90 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
22fa0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
22fb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
22fc0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
22fd0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
22fe0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
22ff0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
23000 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
23010 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
23020 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
23030 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
23040 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
23050 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
23060 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
23070 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
23080 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69   do the conversi
23090 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  on.** automatica
230a0 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
230b0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
230c0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
230d0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70  s that.** are ap
230e0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
230f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
23100 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
23110 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
23120 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
23130 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
23140 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
23150 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
23160 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23170 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23180 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
23190 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
231a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
231b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
231c0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
231d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
231e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
231f0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23200 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23210 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
23220 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
23230 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23240 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23250 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
23260 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
23270 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
23280 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
23290 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
232a0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
232b0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
232c0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
232d0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
232e0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
232f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
23300 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d   as for INTEGER-
23310 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
23320 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
23330 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
23340 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
23350 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
23360 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
23370 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23380 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
23390 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
233a0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
233b0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
233c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
233d0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
233e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
233f0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
23400 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
23410 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
23420 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
23430 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
23440 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
23450 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
23460 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23470 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
23480 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
23490 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
234a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
234b0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
234c0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
234d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
234e0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
234f0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
23500 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
23510 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
23520 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23530 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
23540 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
23550 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
23560 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
23570 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  e>.**.** The tab
23580 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
23590 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
235a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
235b0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
235c0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
235d0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
235e0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
235f0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
23600 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71  has its.** on eq
23610 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uavalent interna
23620 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
23630 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
23640 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
23650 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
23660 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
23670 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
23680 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
23690 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
236a0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
236b0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
236c0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
236d0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
236e0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
236f0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23700 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
23710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23720 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
23730 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
23740 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
23750 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a   invalidated. .*
23760 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
23770 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
23780 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
23790 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
237a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
237b0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
237c0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
237d0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
237e0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
237f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23800 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  () .**          
23810 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
23820 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
23830 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
23840 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
23850 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20  *          need 
23860 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
23870 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f  he string.</p></
23880 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70  li>.**.** <li><p
23890 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
238a0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
238b0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
238c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
238d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
238e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
238f0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23900 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
23910 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
23920 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
23930 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c  o UTF-16.</p></l
23940 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
23950 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
23960 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
23970 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
23980 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23990 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
239a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
239b0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
239c0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
239d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
239e0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54  *          to UT
239f0 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  F-8.</p></li>.**
23a00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
23a10 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
23a20 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
23a30 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
23a40 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
23a50 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
23a60 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
23a70 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
23a80 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
23a90 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
23aa0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
23ab0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
23ac0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
23ad0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
23ae0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
23af0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
23b00 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
23b10 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
23b20 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
23b30 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ime it is.** not
23b40 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
23b50 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
23b60 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
23b70 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a  invalidated.  .*
23b80 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
23b90 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
23ba0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
23bb0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
23bc0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
23bd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
23be0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
23bf0 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  *  <ul>.**  <li>
23c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23c10 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
23c20 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23c30 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
23c40 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
23c50 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
23c60 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
23c70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
23c80 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
23c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23ca0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
23cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23cc0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
23cd0 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e    </ul>.**.** In
23ce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
23cf0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
23d00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23d10 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t(), sqlite3_col
23d20 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f  umn_blob(),.** o
23d30 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
23d40 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
23d50 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
23d60 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73  ult into the des
23d70 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20  ired.** format, 
23d80 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
23d90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23da0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
23db0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
23dc0 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69  o.** find the si
23dd0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
23de0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
23df0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
23e00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
23e10 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
23e20 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
23e30 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
23e40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20  lumn_bytes16(). 
23e50 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d   And do not.** m
23e60 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
23e70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23e80 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  6() with calls t
23e90 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
23ea0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
23eb0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
23ec0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
23ed0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
23ee0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
23ef0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
23f00 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
23f10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23f20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
23f30 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
23f40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23f50 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
23f60 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
23f70 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
23f80 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69  s.** and blobs i
23f90 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
23fa0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
23fb0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
23fc0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
23fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
23fe0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
23ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24000 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20  t()], etc. into 
24010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
24020 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
24030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
24040 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
24050 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
24060 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
24070 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24080 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
24090 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
240a0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
240b0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
240c0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
240d0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
240e0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
240f0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
24100 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
24110 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
24120 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
24130 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
24140 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
24150 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24160 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65  .** {F13803} The
24170 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24180 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
24190 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
241a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
241b0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
241c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
241d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
241e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
241f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24200 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f  nt] S into a blo
24210 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  b and then retur
24220 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
24230 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24240 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
24250 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20  .**.** {F13806} 
24260 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24270 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20  umn_bytes(S,N)] 
24280 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24290 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
242a0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
242b0 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72  s in the blob or
242c0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
242d0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
242e0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
242f0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
24300 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
24310 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
24320 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
24330 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
24340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24350 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  ob(S,N)] or.**  
24360 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24370 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
24380 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  )]..**.** {F1380
24390 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
243a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53  column_bytes16(S
243b0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
243c0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
243d0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
243e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
243f0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
24400 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
24410 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
24420 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
24430 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
24440 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
24450 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
24460 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
24470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24480 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6(S,N)]..**.** {
24490 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c  F13812} The [sql
244a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
244b0 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  le(S,N)] interfa
244c0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
244d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
244e0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
244f0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24500 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24510 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24530 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   S into a floati
24540 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
24550 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
24560 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
24570 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
24580 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20  ** {F13815} The 
24590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
245a0 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  int(S,N)] interf
245b0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
245c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
245d0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
245e0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
245f0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24620 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
24630 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24640 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24650 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
24660 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
24670 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
24680 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b  * {F13818} The [
24690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
246a0 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
246b0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
246c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
246d0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
246e0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
246f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24700 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24720 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
24730 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24740 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
24750 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
24760 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
24770 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d  ..**.** {F13821}
24780 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24790 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
247a0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
247b0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
247c0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
247d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
247e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
247f0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24800 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24810 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
24820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24830 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20   UTF-8 .**      
24840 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
24850 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24860 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
24870 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20  .**.** {F13824} 
24880 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24890 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
248a0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
248b0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
248c0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
248d0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
248e0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
248f0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
24900 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24910 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
24920 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
24930 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
24940 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
24950 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
24960 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
24970 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
24980 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24990 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
249a0 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68  *.** {F13827} Th
249b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
249c0 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
249d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
249e0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
249f0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
24a00 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
24a10 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
24a20 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
24a30 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
24a40 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
24a50 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
24a60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24a70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
24a80 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24a90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24aa0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24ab0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24ac0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
24ad0 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71  {F13830} The [sq
24ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
24af0 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ue(S,N)] interfa
24b00 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  ce returns a.** 
24b10 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
24b20 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   to an [unprotec
24b30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24b40 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68  e] object for th
24b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
24b60 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
24b70 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
24b80 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bb0 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  t] S..*/.const v
24bc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24bd0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
24be0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24bf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24c00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
24c10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24c20 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24c30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24c40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24c50 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
24c60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24c70 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24c80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24c90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24ca0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
24cb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24cc0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
24cd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24ce0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
24cf0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24d00 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
24d10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
24d20 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
24d30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24d40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24d60 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
24d70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
24d80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24d90 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
24da0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24db0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
24dc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
24dd0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
24de0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
24df0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e00 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
24e10 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
24e20 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a  ect {F13300}.**.
24e30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
24e40 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
24e50 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
24e60 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72  delete a .** [pr
24e70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24e80 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ]. If the statem
24e90 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75  ent was.** execu
24ea0 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
24eb0 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  , or not execute
24ec0 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53  d at all, then S
24ed0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
24ee0 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63  rned..** If exec
24ef0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
24f00 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
24f10 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  en an .** [error
24f20 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
24f30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a  ded error code].
24f40 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
24f50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24f60 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
24f70 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
24f80 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
24f90 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
24fa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24fb0 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  t].  If the virt
24fc0 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
24fd0 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  not .** complete
24fe0 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
24ff0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
25000 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
25010 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
25020 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
25030 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20  r an interrupt. 
25040 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69   (See [sqlite3_i
25050 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a  nterrupt()].) .*
25060 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
25070 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
25080 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
25090 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c  sactions cancell
250a0 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69  ed,  .** dependi
250b0 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
250c0 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
250d0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
250e0 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
250f0 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
25100 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
25110 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  NTS:.**.** {F113
25120 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
25130 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e  _finalize(S)] in
25140 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73  terface destroys
25150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
25160 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25170 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
25180 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ases all.**     
25190 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
251a0 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68  file resources h
251b0 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65  eld by that obje
251c0 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  ct..**.** {F1130
251d0 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
251e0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
251f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25200 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
25210 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
25220 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
25230 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a  ned an error,.**
25240 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
25250 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25260 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
25270 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f  t same error..*/
25280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
25290 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
252a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
252b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
252c0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
252d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
252e0 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13330}.**.** Th
252f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
25300 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
25310 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
25320 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25330 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
25340 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20  .** back to its 
25350 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
25360 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
25370 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
25380 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
25390 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
253a0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
253b0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
253c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
253d0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
253e0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
253f0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
25400 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
25410 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
25420 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
25430 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
25440 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {F11332} The [s
25450 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25460 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
25470 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
25480 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
25490 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
254a0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
254b0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
254c0 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66  *.** {F11334} If
254d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
254e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
254f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a  3_step(S)] for .
25500 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25520 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
25530 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
25540 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
25550 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
25560 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
25570 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
25580 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
25590 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
255a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
255b0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
255c0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
255d0 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65   {F11336} If the
255e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
255f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25600 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  ep(S)] for.**   
25610 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
25620 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
25630 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
25640 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
25650 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
25660 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
25670 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
25680 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
25690 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {F11338} The [s
256a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
256b0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
256c0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
256d0 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
256e0 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
256f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
25700 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72  ings] on [prepar
25710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
25720 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25730 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
25740 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
25750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
25760 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
25770 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  SQL Functions {F
25780 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  16100}.** KEYWOR
25790 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
257a0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
257b0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77   .**.** These tw
257c0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
257d0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
257e0 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20  as.** "function 
257f0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
25800 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20  s") are used to 
25810 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
25820 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a  s or aggregates.
25830 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  ** or to redefin
25840 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
25850 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
25860 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
25870 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20  egates.  The.** 
25880 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20  difference only 
25890 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
258a0 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
258b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
258c0 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
258d0 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
258e0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
258f0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
25900 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
25910 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25920 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
25930 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
25940 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
25950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
25960 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25970 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25980 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
25990 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
259a0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
259b0 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
259c0 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
259d0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
259e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
259f0 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c  ction] internall
25a00 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66  y, then SQL.** f
25a10 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
25a20 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
25a30 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74  lly to each [dat
25a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25a50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
25a60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25a70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
25a90 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
25aa0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
25ab0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
25ac0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
25ad0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
25ae0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
25af0 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
25b00 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
25b10 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
25b20 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
25b30 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
25b40 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
25b50 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
25b60 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25b70 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
25b80 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
25b90 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
25ba0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
25bb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
25bc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
25bd0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
25be0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25bf0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
25c00 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
25c10 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
25c20 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
25c30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
25c40 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
25c50 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
25c60 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
25c70 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
25c80 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
25c90 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
25ca0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
25cb0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
25cc0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
25cd0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
25ce0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
25cf0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
25d00 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
25d10 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
25d20 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
25d30 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
25d40 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
25d50 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
25d60 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
25d70 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
25d80 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
25d90 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
25da0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
25db0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
25dc0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
25dd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
25de0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
25df0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
25e00 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
25e10 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
25e20 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
25e30 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
25e40 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
25e50 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
25e60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25e70 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
25e80 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
25e90 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
25ea0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
25eb0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
25ec0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
25ed0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
25ee0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
25ef0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
25f00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25f10 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
25f20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
25f30 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
25f40 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
25f50 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
25f60 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
25f70 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
25f80 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
25f90 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
25fa0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
25fb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
25fc0 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
25fd0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
25fe0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
25ff0 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
26000 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
26010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
26020 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
26030 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
26040 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
26050 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
26060 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
26070 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
26080 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
26090 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
260a0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
260b0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
260c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
260d0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
260e0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
260f0 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
26100 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
26110 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
26120 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
26130 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
26140 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
26150 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
26160 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
26170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
26180 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
26190 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
261a0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
261b0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
261c0 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
261d0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
261e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
261f0 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
26200 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
26210 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
26220 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
26230 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
26240 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
26250 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
26260 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
26270 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
26280 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
26290 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
262a0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
262b0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
262c0 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
262d0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
262e0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
262f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
26300 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
26310 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
26320 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
26330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
26340 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   used..**.** INV
26350 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26360 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  F16103} The [sql
26370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26380 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66  tion16()] interf
26390 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63  ace behaves exac
263a0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
263b0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72  like [sqlite3_cr
263c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
263d0 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78   in every way ex
263e0 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20  cept that it.** 
263f0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72           interpr
26400 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f  ets the zFunctio
26410 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61  nName argument a
26420 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  s.**          ze
26430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
26440 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
26450 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
26460 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  f as a.**       
26470 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
26480 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  ed UTF-8..**.** 
26490 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65  {F16106} A succe
264a0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
264b0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
264c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
264d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
264e0 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,N,E,...)] inter
264f0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a  face registers.*
26500 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65  *          or re
26510 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20  places callback 
26520 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61  functions in [da
26530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26540 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
26550 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
26560 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
26570 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68  ion named X with
26580 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
26590 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61            and ha
265a0 76 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64  ving a perferred
265b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
265c0 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  f E..**.** {F161
265d0 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  09} A successful
265e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
265f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26600 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
26610 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
26620 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20  replaces the P, 
26630 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75  F, S, and L valu
26640 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f  es from any prio
26650 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20  r calls with.** 
26660 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
26670 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45  e D, X, N, and E
26680 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b   values..**.** {
26690 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16112} The [sql
266a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
266b0 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69  tion(D,X,...)] i
266c0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
266d0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
266e0 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  a return code of
266f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26700 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  if the SQL funct
26710 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a  ion name X is.**
26720 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72            longer
26730 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20   than 255 bytes 
26740 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
26750 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
26760 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d  ..**.** {F16118}
26770 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62   Either F must b
26780 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  e NULL and S and
26790 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20   L are non-NULL 
267a0 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20  or else F.**    
267b0 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c        is non-NUL
267c0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
267d0 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73  e NULL, otherwis
267e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
267f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26800 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26810 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73  ,F,S,L)] returns
26820 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
26830 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20  .**.** {F16121} 
26840 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
26850 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
26860 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
26870 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
26880 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
26890 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
268a0 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
268b0 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
268c0 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
268d0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
268e0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
268f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26900 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34  D..**.** {F16124
26910 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
26920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26930 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
26940 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
26950 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
26960 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
26970 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
26980 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63  arameter N (spec
26990 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ifying the numbe
269a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
269b0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
269c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62  e SQL function b
269d0 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29  eing registered)
269e0 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   is less.**     
269f0 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20       than -1 or 
26a00 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
26a10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d  ..**.** {F16127}
26a20 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e   When N is non-n
26a30 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71  egative, the [sq
26a40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26a50 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
26a60 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26a70 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
26a80 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
26a90 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
26aa0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
26ab0 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
26ac0 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
26ad0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
26ae0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26af0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
26b00 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
26b10 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {F16130} When N
26b20 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
26b30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26b40 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
26b50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
26b60 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
26b70 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
26b80 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
26b90 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
26ba0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
26bb0 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ith any number o
26bc0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
26bd0 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e  ** {F16133} When
26be0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
26bf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26c00 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
26c10 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
26c20 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
26c30 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26c40 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26c50 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   X.**          a
26c60 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c  nd when one impl
26c70 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e  ementation has N
26c80 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65  >=0 and the othe
26c90 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20  r has N=(-1).** 
26ca0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70           the imp
26cb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
26cc0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73   a non-zero N is
26cd0 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
26ce0 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20  * {F16136} When 
26cf0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26d00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26d10 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a  n(D,X,N,E,...)].
26d20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
26d30 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
26d40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
26d50 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
26d60 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  n X with.**     
26d70 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75       the same nu
26d80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26d90 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66  s N but with dif
26da0 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  ferent.**       
26db0 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20     encodings E, 
26dc0 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  then the impleme
26dd0 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20  ntation where E 
26de0 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20  matches the.**  
26df0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
26e00 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65   encoding is pre
26e10 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ferred..**.** {F
26e20 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67  16139} For an ag
26e30 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
26e40 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69  tion created usi
26e50 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
26e60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26e70 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
26e80 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69  P,0,S,L)] the fi
26e90 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20  nializer.**     
26ea0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20       function L 
26eb0 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69  will always be i
26ec0 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
26ed0 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nce if the.**   
26ee0 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63         step func
26ef0 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64  tion S is called
26f00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
26f10 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34  es..**.** {F1614
26f20 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  2} When SQLite i
26f30 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68  nvokes either th
26f40 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70  e xFunc or xStep
26f50 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20   function of.** 
26f60 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c           an appl
26f70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26f80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
26f90 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65  aggregate create
26fa0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
26fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26fc0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20  _function()] or 
26fd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26fe0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a  function16()],.*
26ff0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
27000 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71  the array of [sq
27010 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27020 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74  ects passed as t
27030 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
27040 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61  hird parameter a
27050 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65  re always [prote
27060 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27070 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  ue] objects..*/.
27080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
27090 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
270a0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
270b0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
270c0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
270d0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
270e0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
270f0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
27100 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
27110 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
27120 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
27130 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
27140 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
27150 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
27160 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
27170 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
27180 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
27190 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
271a0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
271b0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
271c0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
271d0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
271e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
271f0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
27200 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
27210 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
27220 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
27230 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
27240 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
27250 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
27260 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
27270 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
27280 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
27290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
272a0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20   Text Encodings 
272b0 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54  {F10267}.**.** T
272c0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
272d0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
272e0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
272f0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
27300 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
27310 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
27320 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
27330 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
27340 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
27350 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
27360 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
27370 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
27380 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
27390 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
273a0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
273b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
273c0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
273d0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
273e0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
273f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27400 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
27410 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27420 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
27430 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
27440 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
27450 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
27460 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75  REF: Obsolete Fu
27470 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
27480 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
27490 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65  e all now obsole
274a0 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  te.  In order to
274b0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
274c0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
274d0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
274e0 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75  code, we continu
274f0 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20  e to support.** 
27500 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
27510 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64    However, new d
27520 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65  evelopment proje
27530 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  cts should avoid
27540 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
27550 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27560 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
27570 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
27580 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
27590 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
275a0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
275b0 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
275c0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  hey do..*/.int s
275d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
275e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
275f0 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71  ontext*);.int sq
27600 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
27610 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
27620 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
27630 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
27640 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
27650 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
27660 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
27670 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69  cover(void);.voi
27680 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
27690 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
276a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
276b0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
276c0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
276d0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
276e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
276f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27700 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
27710 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
27720 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30  r Values {F15100
27730 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  }.**.** The C-la
27740 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
27750 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
27760 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
27770 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
27780 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
27790 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
277a0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
277b0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
277c0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
277d0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
277e0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
277f0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
27800 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
27810 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
27820 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
27830 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27840 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
27850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27860 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
27870 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
27880 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
27890 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
278a0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
278b0 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
278c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
278d0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
278e0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
278f0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
27900 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27910 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
27920 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
27930 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27940 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
27950 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
27960 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
27970 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
27980 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
27990 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
279a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
279b0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
279c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
279d0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
279e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
279f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27a00 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
27a10 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
27a20 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
27a30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27a40 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
27a50 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
27a60 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
27a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
27a80 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
27a90 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
27aa0 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  ponding .** [sql
27ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27ac0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
27ad0 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78  n_* routines] ex
27ae0 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68  cept that .** th
27af0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
27b00 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
27b10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27b20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  lue] object poin
27b30 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ter.** instead o
27b40 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  f an [sqlite3_st
27b50 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
27b60 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
27b70 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
27b80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
27b90 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
27ba0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
27bb0 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a   UTF16 string.**
27bc0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
27bd0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
27be0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
27bf0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
27c00 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
27c10 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
27c20 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
27c30 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
27c40 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73  ct UTF16 strings
27c50 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
27c60 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
27c70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
27c80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27c90 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
27ca0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
27cb0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
27cc0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
27cd0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
27ce0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
27cf0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
27d00 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
27d10 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
27d20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
27d30 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
27d40 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
27d50 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
27d60 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
27d70 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
27d80 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
27d90 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75  ords if the valu
27da0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
27db0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
27dc0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
27dd0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
27de0 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69  s done.  Otherwi
27df0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
27e00 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a   occurs.  The .*
27e10 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
27e20 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
27e30 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
27e40 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27e50 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
27e60 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
27e70 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
27e80 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  at the pointer t
27e90 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  hat.** is return
27ea0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
27eb0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
27ec0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27ed0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
27ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27ef0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
27f00 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
27f10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27f20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
27f30 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
27f40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27f50 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
27f60 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
27f70 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
27f80 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
27f90 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72    .**.** These r
27fa0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
27fb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27fc0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
27fd0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
27fe0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
27ff0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
28000 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
28010 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ..**.**.** INVAR
28020 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
28030 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5103} The [sqlit
28040 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
28050 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28060 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
28070 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
28080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28090 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62  bject V into a b
280a0 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
280b0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
280c0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
280d0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
280e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36  e..**.** {F15106
280f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
28100 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69  alue_bytes(V)] i
28110 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28120 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28130 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28140 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
28150 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
28160 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
28170 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
28180 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
28190 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
281a0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
281b0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
281c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
281d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
281e0 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  (V)] or.**      
281f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
28200 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a  ue_text(V)]..**.
28210 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20  ** {F15109} The 
28220 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
28230 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72  ytes16(V)] inter
28240 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
28260 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28270 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
28280 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
28290 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
282a0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
282b0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
282c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
282d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
282e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
282f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28300 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20  text16(V)],.**  
28310 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
28320 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28330 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  V)], or [sqlite3
28340 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
28350 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
28360 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
28370 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29  _value_double(V)
28380 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28390 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
283a0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
283b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
283c0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66  bject V into a f
283d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
283e0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
283f0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
28400 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
28410 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d  ..**.** {F15115}
28420 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28430 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65  lue_int(V)] inte
28440 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28450 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
28460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28470 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28480 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
28490 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
284a0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
284b0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
284c0 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
284d0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
284e0 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71  {F15118} The [sq
284f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
28500 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  4(V)] interface 
28510 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28520 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
28530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28540 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28550 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
28560 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
28570 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
28580 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
28590 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
285a0 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  F15121} The [sql
285b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
285c0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
285d0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
285e0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
285f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28600 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
28610 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28620 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20   UTF-8 .**      
28630 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
28640 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28650 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
28660 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20  .**.** {F15124} 
28670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28680 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e  ue_text16(V)] in
28690 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
286a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
286b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
286c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
286d0 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
286e0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
286f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
28700 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
28710 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
28720 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
28730 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
28740 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
28750 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
28760 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  15127} The [sqli
28770 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28780 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  be(V)] interface
28790 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
287a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
287b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
287c0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
287d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
287e0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
287f0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
28800 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
28810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
28820 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
28830 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
28840 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
28850 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71  {F15130} The [sq
28860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28870 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16le(V)] interfa
28880 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
28890 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
288a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
288b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
288c0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
288d0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
288e0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
288f0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
28900 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
28910 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
28920 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28930 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
28940 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68  *.** {F15133} Th
28950 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28960 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
28970 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
28980 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b          one of [
28990 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53  SQLITE_NULL], [S
289a0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
289b0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a  [SQLITE_FLOAT],.
289c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
289d0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53  ITE_TEXT], or [S
289e0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
289f0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
28a00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
28a10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28a20 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
28a30 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c  F15136} The [sql
28a40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
28a50 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ic_type(V)] inte
28a60 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a  rface converts.*
28a70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
28a80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28a90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28aa0 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e  V into either an
28ab0 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20   integer or.**  
28ac0 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69          a floati
28ad0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69  ng point value i
28ae0 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77  f it can do so w
28af0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a  ithout loss of.*
28b00 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72  *          infor
28b10 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75  mation, and retu
28b20 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  rns one of [SQLI
28b30 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20  TE_NULL],.**    
28b40 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e        [SQLITE_IN
28b50 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
28b60 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
28b70 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  TEXT], or.**    
28b80 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c        [SQLITE_BL
28b90 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
28ba0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
28bb0 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
28bc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28bd0 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20   object V after 
28be0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  the conversion a
28bf0 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  ttempt..*/.const
28c00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
28c10 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
28c20 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28c40 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
28c50 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
28c60 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
28c70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
28c80 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
28c90 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
28ca0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
28cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
28cc0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
28cd0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
28ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
28cf0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
28d00 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
28d10 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
28d20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
28d30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
28d40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28d50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
28d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28d70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28d80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28d90 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
28da0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
28db0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
28dc0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
28dd0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28de0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
28df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28e10 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
28e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28e30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28e40 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
28e50 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
28e60 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a  ext {F16210}.**.
28e70 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
28e80 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
28e90 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
28ea0 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
28eb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
28ec0 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
28ed0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
28ee0 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66  tate.  .** The f
28ef0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
28f00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28f10 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e  context() routin
28f20 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  e is.** is calle
28f30 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  d for a particul
28f40 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51  ar aggregate, SQ
28f50 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e  Lite allocates n
28f60 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  Bytes of memory.
28f70 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65  ** zeros that me
28f80 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
28f90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
28fa0 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20  t..** On second 
28fb0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
28fc0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
28fd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
28fe0 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  t().** for the s
28ff0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
29000 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68  nction index, th
29010 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
29020 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
29030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29040 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65  .** of the aggre
29050 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65  gate can use the
29060 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72   returned buffer
29070 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64   to accumulate d
29080 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ata..**.** SQLit
29090 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
290a0 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61  frees the alloca
290b0 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20  ted buffer when 
290c0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
290d0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
290e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
290f0 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  t parameter shou
29100 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  ld be a copy of 
29110 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
29120 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
29130 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
29140 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
29150 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
29160 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
29170 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
29180 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
29190 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
291a0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
291b0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
291c0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
291d0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
291e0 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
291f0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
29200 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
29210 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29220 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68  *.** {F16211} Th
29230 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
29240 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61  on of [sqlite3_a
29250 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29260 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  (C,N)] for.**   
29270 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75         a particu
29280 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
29290 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  an aggregate fun
292a0 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72  ction (for a par
292b0 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20  ticular.**      
292c0 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63      context C) c
292d0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
292e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74  allocation N byt
292f0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
29300 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
29310 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
29320 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
29330 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69   to the allocati
29340 6f 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oned.**         
29350 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
29360 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d  F16213} If a mem
29370 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
29380 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
29390 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
293a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
293b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
293c0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
293d0 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a  n returns 0..**.
293e0 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f  ** {F16215} Seco
293f0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
29400 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
29410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29420 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29430 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
29440 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65  r the same conte
29450 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20  xt pointer C.** 
29460 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20           ignore 
29470 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
29480 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
29490 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65  nter to the same
294a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f  .**          blo
294b0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74  ck of memory ret
294c0 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72  urned by the fir
294d0 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  st invocation..*
294e0 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68  *.** {F16217} Th
294f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
29500 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61  ed by [sqlite3_a
29510 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29520 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20  (C,N)] is.**    
29530 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61        automatica
29540 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65  lly freed on the
29550 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73   next call to [s
29560 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
29570 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
29580 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29590 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ()] for the [pre
295a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
295b0 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
295c0 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72          the aggr
295d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61  egate function a
295e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
295f0 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69  ontext C..*/.voi
29600 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
29610 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
29620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
29630 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
29640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
29650 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
29660 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a  ions {F16240}.**
29670 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29680 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
29690 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
296a0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
296b0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
296c0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
296d0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
296e0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
296f0 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74  f the the [sqlit
29700 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29710 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
29720 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29730 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
29740 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
29750 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
29760 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
29770 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
29780 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  on. {END}.**.** 
29790 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
297a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
297b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
297c0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
297d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
297e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
297f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
29800 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
29810 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b  * {F16243} The [
29820 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29830 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  a(C)] interface 
29840 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29850 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
29860 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    P pointer from
29870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
29880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
29890 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
298a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
298b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
298c0 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
298d0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
298e0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
298f0 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
29900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
29910 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
29920 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
29930 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
29940 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
29950 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
29960 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
29970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29980 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
29990 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
299a0 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F16250}.**.** 
299b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
299c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
299d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
299e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
299f0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
29a00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29a10 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
29a20 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
29a30 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74  f the the [sqlit
29a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29a50 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
29a60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29a70 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
29a80 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
29a90 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
29aa0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
29ab0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
29ac0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
29ad0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
29ae0 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  253} The [sqlite
29af0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
29b00 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63  dle(C)] interfac
29b10 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
29b20 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
29b30 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72      D pointer fr
29b40 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
29b50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
29b60 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
29b70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
29b80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29b90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
29ba0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
29bb0 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
29bc0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
29bd0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
29be0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29c00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
29c10 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
29c20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
29c30 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
29c40 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
29c50 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
29c60 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
29c70 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a  ata {F16270}.**.
29c80 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
29c90 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
29ca0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
29cb0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
29cc0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
29cd0 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74  te meta-data wit
29ce0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
29cf0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
29d00 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
29d10 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
29d20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
29d30 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
29d40 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
29d50 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
29d60 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
29d70 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
29d80 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20  iated meta-data 
29d90 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
29da0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
29db0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
29dc0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
29dd0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
29de0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
29df0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
29e00 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
29e10 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
29e20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
29e30 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
29e40 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  -data associated
29e50 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
29e60 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
29e70 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
29e80 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
29e90 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
29ea0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
29eb0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
29ec0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
29ed0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
29ee0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
29ef0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
29f00 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
29f10 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
29f20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
29f30 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
29f40 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
29f50 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
29f60 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
29f70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
29f80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
29f90 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  a-data.** associ
29fa0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
29fb0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
29fc0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
29fd0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
29fe0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
29ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2a010 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74  * If no meta-dat
2a020 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20  a has been ever 
2a030 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2a040 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   Nth.** argument
2a050 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2a060 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72  , or if the coor
2a070 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
2a080 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
2a090 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2a0a0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2a0b0 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71  was set, then sq
2a0c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2a0d0 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  a().** returns a
2a0e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2a0f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a100 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2a110 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2a120 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
2a130 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2a140 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2a150 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  as the meta-data
2a160 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2a170 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2a180 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a190 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2a1a0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2a1b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2a1c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2a1d0 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2a1e0 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2a1f0 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2a200 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20  oyed. .** If it 
2a210 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
2a220 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2a230 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a  the destructor .
2a240 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
2a250 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
2a260 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a270 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2a280 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64  on.** the meta-d
2a290 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
2a2a0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
2a2b0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
2a2c0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
2a2d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a2e0 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
2a2f0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
2a300 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
2a310 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
2a320 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
2a330 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64   and drop meta-d
2a340 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61  ata on.** any pa
2a350 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
2a360 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
2a370 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
2a380 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74  uarantee.** is t
2a390 68 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74  hat the destruct
2a3a0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2a3b0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2a3c0 61 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70  adata is.** drop
2a3d0 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72  ped..**.** In pr
2a3e0 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74  actice, meta-dat
2a3f0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2a400 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2a410 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2a420 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2a430 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2a440 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2a450 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2a460 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2a470 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2a480 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2a490 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2a4a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2a4b0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2a4c0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2a4d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2a4e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2a4f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32  S:.**.** {F16272
2a500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2a510 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2a520 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a530 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2a540 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2a550 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2a560 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2a570 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2a580 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2a590 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2a5a0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2a5b0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2a5c0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2a5d0 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2a5e0 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2a5f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
2a600 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2a610 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2a620 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2a630 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2a640 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2a650 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2a660 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2a670 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2a680 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2a690 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  t.**          C.
2a6a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20  .**.** {F16276} 
2a6b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2a6c0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2a6d0 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
2a6e0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  e argument.**   
2a6f0 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20         which is 
2a700 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69  the metadata poi
2a710 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67  nter P following
2a720 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
2a730 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2a740 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2a750 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74  P,D)] when SQLit
2a760 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
2a770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2a780 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a   metadata..**.**
2a790 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65   {F16277} SQLite
2a7a0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20   ceases to hold 
2a7b0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20  metadata for an 
2a7c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  SQL function par
2a7d0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
2a7e0 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75     when the valu
2a7f0 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65  e of that parame
2a800 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  ter changes..**.
2a810 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e  ** {F16278} When
2a820 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2a830 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2a840 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2a850 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20  destructor.**   
2a860 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64         is called
2a870 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d   for any prior m
2a880 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2a890 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
2a8a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2a8b0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20        context C 
2a8c0 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e  and parameter N.
2a8d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20  .**.** {F16279} 
2a8e0 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c  SQLite will call
2a8f0 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72   destructors for
2a900 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74   any metadata it
2a910 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20   is holding.**  
2a920 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72          in a par
2a930 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65  ticular [prepare
2a940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77  d statement] S w
2a950 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  hen either.**   
2a960 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2a970 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71  reset(S)] or [sq
2a980 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2a990 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f  )] is called..*/
2a9a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2a9b0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2a9c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2a9d0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2a9e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2a9f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2aa00 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2aa10 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2aa20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aa30 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2aa40 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2aa50 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2aa60 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F10280}.**.** 
2aa70 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2aa80 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
2aa90 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
2aaa0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
2aab0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
2aac0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
2aad0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2aae0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
2aaf0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
2ab00 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2ab10 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2ab20 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2ab30 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2ab40 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2ab50 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2ab60 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2ab70 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2ab80 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
2ab90 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
2aba0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2abb0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2abc0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2abd0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2abe0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2abf0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2ac00 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2ac10 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2ac20 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2ac30 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2ac40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2ac50 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2ac60 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2ac70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2ac80 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2ac90 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2aca0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2acb0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2acc0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2acd0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2ace0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2acf0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2ad00 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2ad10 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2ad20 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2ad30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2ad40 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2ad50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2ad60 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2ad70 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2ad80 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a  on {F16400}.**.*
2ad90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2ada0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2adb0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2adc0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2add0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2ade0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2adf0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2ae00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2ae10 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2ae20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ae30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2ae40 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2ae50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2ae60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2ae70 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2ae80 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a  much like the .*
2ae90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2aea0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2aeb0 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66  ind_*] family of
2aec0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a   functions used.
2aed0 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ** to bind value
2aee0 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2aef0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2af00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2af10 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  Refer to the.** 
2af20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2af30 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2af40 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  d_* documentatio
2af50 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
2af60 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2af70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2af80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2af90 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2afa0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2afb0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2afc0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2afd0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2afe0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2aff0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2b000 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2b010 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2b020 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2b030 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2b040 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2b050 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73  meter. .** The s
2b060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2b070 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63  roblob() inerfac
2b080 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
2b090 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2b0a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2b0b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2b0c0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
2b0d0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
2b0e0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
2b0f0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
2b100 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2b110 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b120 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
2b130 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2b140 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
2b150 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2b160 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2b170 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2b180 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
2b190 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b1a0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
2b1b0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
2b1c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2b1d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b1e0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2b1f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b200 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
2b210 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
2b220 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
2b230 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
2b240 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51  exception..** SQ
2b250 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
2b260 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
2b270 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
2b280 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
2b290 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2b2a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
2b2b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
2b2c0 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
2b2d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2b2e0 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  .  SQLite interp
2b2f0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2b300 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2b310 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2b320 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2b330 55 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  UTF8. SQLite.** 
2b340 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2b350 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2b360 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b370 36 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20  6() as UTF16 in 
2b380 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
2b390 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
2b3a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2b3b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b3c0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2b3d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b3e0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
2b3f0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2b400 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
2b410 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
2b420 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
2b430 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2b440 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
2b450 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2b460 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2b470 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2b480 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2b490 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2b4a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2b4b0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2b4c0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2b4d0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2b4e0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2b4f0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2b500 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2b510 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b520 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2b530 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2b540 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
2b550 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63  outines make a c
2b560 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79  opy private copy
2b570 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
2b580 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
2b590 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
2b5a0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
2b5b0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
2b5c0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
2b5d0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
2b5e0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
2b5f0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
2b600 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  rm..** The sqlit
2b610 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2b620 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2b630 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2b640 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2b650 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2b660 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2b670 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2b680 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  on.  By default,
2b690 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
2b6a0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
2b6b0 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e  OR.  A subsequen
2b6c0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2b6d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2b6e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2b6f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2b700 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
2b710 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
2b720 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ERROR..**.** The
2b730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b740 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
2b750 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2b760 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  .** to throw an 
2b770 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
2b780 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
2b790 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
2b7a0 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e  g.** to represen
2b7b0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
2b7c0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2b7d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73  nterface.** caus
2b7e0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2b7f0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  ow an exception 
2b800 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2b810 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  the a.** memory 
2b820 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2b830 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2b840 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2b850 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2b860 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b870 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2b880 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b890 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2b8a0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
2b8b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2b8c0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2b8d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
2b8e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b8f0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2b900 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2b910 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2b920 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b930 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b940 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2b950 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2b960 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2b970 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2b980 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2b990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2b9a0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
2b9b0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2b9c0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2b9d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b9e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2b9f0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  be NULL..**.** T
2ba00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ba10 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2ba20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2ba30 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ), .** sqlite3_r
2ba40 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
2ba50 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
2ba60 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
2ba70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
2ba80 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
2ba90 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
2baa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2bab0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
2bac0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
2bad0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
2bae0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
2baf0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2bb00 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
2bb10 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
2bb20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
2bb30 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2bb40 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
2bb50 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2bb60 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2bb70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2bb80 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2bb90 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2bba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2bbb0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
2bbc0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2bbd0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2bbe0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2bbf0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2bc00 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
2bc10 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
2bc20 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
2bc30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a   2nd parameter .
2bc40 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2bc50 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2bc60 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
2bc70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2bc80 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2bc90 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2bca0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
2bcb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
2bcc0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
2bcd0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
2bce0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
2bcf0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
2bd00 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
2bd10 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
2bd20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
2bd30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
2bd40 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2bd50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2bd60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bd70 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2bd80 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2bd90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2bda0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
2bdb0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2bdc0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
2bdd0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
2bde0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2bdf0 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73  text or blob res
2be00 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
2be10 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
2be20 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2be30 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
2be40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2be50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2be60 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2be70 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2be80 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2be90 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2bea0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2beb0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73  hen.** SQLite as
2bec0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2bed0 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2bee0 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73  lt is constant s
2bef0 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73  pace and.** does
2bf00 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70   not copy the sp
2bf10 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65  ace or call a de
2bf20 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
2bf30 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2bf40 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2bf50 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2bf60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2bf70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bf80 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2bf90 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2bfa0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2bfb0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2bfc0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
2bfd0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
2bfe0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
2bff0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
2c000 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
2c010 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
2c020 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c030 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
2c040 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
2c050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c060 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2c070 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2c080 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2c090 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c0a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2c0b0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2c0c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c0d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c0e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2c0f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2c100 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2c110 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2c120 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2c130 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2c140 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2c150 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  so that [sqlite3
2c160 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
2c170 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
2c180 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
2c190 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
2c1a0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2c1b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2c1c0 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
2c1d0 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74  harm..** A [prot
2c1e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c1f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
2c200 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
2c210 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
2c220 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c230 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
2c240 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
2c250 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
2c260 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c270 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
2c280 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
2c290 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
2c2a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c2b0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2c2c0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
2c2d0 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20  rent thread .** 
2c2e0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
2c2f0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
2c300 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c310 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
2c320 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  cieved.** the [s
2c330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2c340 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
2c350 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2c360 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
2c370 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2c380 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
2c390 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
2c3a0 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
2c3b0 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
2c3c0 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20  ** {F16406} The 
2c3d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c3e0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
2c3f0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c400 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c410 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2c420 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2c430 65 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73  e a blob that is
2c440 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
2c450 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
2c460 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
2c470 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
2c480 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20  .**.** {F16409} 
2c490 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2c4a0 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
2c4b0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c4c0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c4d0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c4e0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c4f0 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
2c500 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
2c510 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54  **.** {F16412} T
2c520 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c530 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
2c540 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c550 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
2c560 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
2c570 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c580 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
2c590 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
2c5a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2c5b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
2c5c0 61 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73  a UTF8 error mes
2c5d0 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d  sage copied from
2c5e0 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20   V up to the.** 
2c5f0 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a           first z
2c600 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69  ero byte or unti
2c610 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65  l N bytes are re
2c620 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
2c630 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2c640 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
2c650 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c660 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
2c670 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2c680 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2c690 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2c6a0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c6b0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2c6c0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2c6d0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
2c6e0 52 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e  R] and a UTF16 n
2c6f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2c700 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
2c710 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65  *          copie
2c720 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74  d from V up to t
2c730 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2c740 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69  rminator or unti
2c750 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  l N bytes.**    
2c760 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69        are read i
2c770 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
2c780 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20  .**.** {F16418} 
2c790 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2c7a0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2c7b0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
2c7c0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
2c7d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
2c7e0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
2c7f0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
2c800 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
2c810 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
2c820 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f       [SQLITE_TOO
2c830 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72  BIG] and an appr
2c840 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
2c850 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssage..**.** {F1
2c860 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6421} The [sqlit
2c870 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2c880 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66  nomem(C)] interf
2c890 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
2c8a0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2c8b0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
2c8c0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c8d0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
2c8e0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
2c8f0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2c900 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20  E_NOMEM] and an 
2c910 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
2c920 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
2c930 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73   {F16424} The [s
2c940 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2c950 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69  ror_code(C,E)] i
2c960 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c970 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2c980 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2c990 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
2c9a0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
2c9b0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
2c9c0 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20  de E..**        
2c9d0 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73    The error mess
2c9e0 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68  age text is unch
2c9f0 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  anged..**.** {F1
2ca00 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6427} The [sqlit
2ca10 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c  e3_result_int(C,
2ca20 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2ca30 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2ca40 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2ca50 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2ca60 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2ca70 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
2ca80 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30  V..**.** {F16430
2ca90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2caa0 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29  esult_int64(C,V)
2cab0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2cac0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2cad0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2cae0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2caf0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
2cb00 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e  integer value V.
2cb10 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20  .**.** {F16433} 
2cb20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2cb30 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74  ult_null(C)] int
2cb40 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2cb50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2cb60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2cb70 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2cb80 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  NULL..**.** {F16
2cb90 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  436} The [sqlite
2cba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2cbb0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
2cbc0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2cbd0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cbe0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2cbf0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
2cc00 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  TF8 string.**   
2cc10 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
2cc20 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
2cc30 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
2cc40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
2cc50 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
2cc60 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
2cc70 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
2cc80 20 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {F16439} The [s
2cc90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cca0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
2ccb0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2ccc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ccd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2cce0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2ccf0 65 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69  e the UTF16 nati
2cd00 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
2cd10 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2cd20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2cd30 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a  st zero if N is.
2cd40 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61  **          nega
2cd50 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2cd60 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
2cd70 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2cd80 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2cd90 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
2cda0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2cdb0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2cdc0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2cdd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2cde0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2cdf0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2ce00 65 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69  e UTF16 big-endi
2ce10 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2ce20 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
2ce30 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2ce40 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  N is.**         
2ce50 20 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20   is negative or 
2ce60 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2ce70 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e  s or V if N is n
2ce80 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2ce90 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20  ** {F16445} The 
2cea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ceb0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2cec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2ced0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cee0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2cef0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cf00 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2cf10 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2cf20 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2cf30 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2cf40 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a  st zero if N is.
2cf50 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61  **          nega
2cf60 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2cf70 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
2cf80 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2cf90 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2cfa0 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
2cfb0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
2cfc0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2cfd0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2cfe0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2cff0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2d000 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63   to be [unprotec
2d010 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d020 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
2d030 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
2d040 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16451} The [sql
2d050 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2d060 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
2d070 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2d080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d090 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2d0a0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2d0b0 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20   N-byte blob of 
2d0c0 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
2d0d0 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {F16454} The [s
2d0e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d0f0 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
2d100 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d110 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
2d120 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
2d130 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
2d140 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
2d150 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
2d160 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2d170 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ning..**.** {F16
2d180 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
2d190 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2d1a0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2d1b0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
2d1c0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2d1d0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d1e0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2d1f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2d200 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2d210 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2d220 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d230 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2d240 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2d250 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d260 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2d270 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
2d280 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
2d290 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
2d2a0 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
2d2b0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
2d2c0 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
2d2d0 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
2d2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
2d2f0 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
2d300 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
2d310 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  F16460} If the D
2d320 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
2d330 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d340 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
2d350 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2d360 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d370 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
2d380 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
2d390 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2d3a0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2d3b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d3c0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
2d3d0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
2d3e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2d3f0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2d400 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
2d410 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
2d420 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
2d430 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
2d440 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
2d450 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2d460 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2d470 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
2d480 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
2d490 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66  *.** {F16463} If
2d4a0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
2d4b0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
2d4c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2d4d0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
2d4e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d4f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2d500 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
2d510 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d520 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
2d530 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d540 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2d550 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
2d560 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2d570 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d580 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
2d590 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
2d5a0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
2d5b0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
2d5c0 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
2d5d0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
2d5e0 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a  ANSIENT] then .*
2d5f0 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
2d600 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2d610 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
2d620 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c  ith V as its onl
2d630 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  y argument.**   
2d640 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68         when it h
2d650 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2d660 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f   the V value..*/
2d670 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d680 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2d690 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d6a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2d6b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2d6c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d6d0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2d6e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2d6f0 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2d700 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2d710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d720 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2d730 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2d740 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2d750 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d760 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d770 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2d780 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2d790 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2d7a0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2d7b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d7c0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2d7d0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2d7e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d7f0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2d800 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2d810 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d820 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2d830 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2d840 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d850 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2d860 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2d870 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2d880 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d890 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2d8a0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2d8b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d8c0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2d8d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2d8e0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d8f0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d910 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2d920 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d930 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d940 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d950 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d960 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2d970 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d980 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2d990 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2d9a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d9b0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2d9c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2d9d0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2d9e0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d9f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2da00 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2da10 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2da20 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2da30 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2da40 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2da50 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2da60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2da70 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2da80 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b  ting Sequences {
2da90 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16600}.**.** Th
2daa0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2dab0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
2dac0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
2dad0 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
2dae0 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
2daf0 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
2db00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2db10 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  t. .**.** The na
2db20 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
2db30 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2db40 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
2db50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2db60 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2db70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2db80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2db90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2dba0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2dbb0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
2dbc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2dbd0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20  llation16(). In 
2dbe0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
2dbf0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
2dc00 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
2dc10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2dc20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
2dc30 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
2dc40 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
2dc50 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
2dc60 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
2dc70 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c  UTF16LE] or [SQL
2dc80 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
2dc90 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
2dca0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
2dcb0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
2dcc0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
2dcd0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
2dce0 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
2dcf0 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
2dd00 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2dd10 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
2dd20 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2dd30 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
2dd40 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
2dd50 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
2dd60 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
2dd70 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
2dd80 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
2dd90 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
2dda0 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
2ddb0 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
2ddc0 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68  * of UTF16 in th
2ddd0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2dde0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2ddf0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
2de00 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
2de10 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
2de20 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
2de30 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
2de40 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
2de50 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
2de60 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
2de70 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
2de80 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2de90 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
2dea0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
2deb0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
2dec0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
2ded0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2dee0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
2def0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
2df00 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
2df10 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
2df20 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
2df30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2df40 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2df50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
2df60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2df70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2df80 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61   as its first pa
2df90 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
2dfa0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
2dfb0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
2dfc0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
2dfd0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
2dfe0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
2dff0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
2e000 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61  by a (length, da
2e010 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta) pair and enc
2e020 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
2e030 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
2e040 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
2e050 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
2e060 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2e070 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
2e080 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
2e090 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  D} The applicati
2e0a0 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
2e0b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
2e0c0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
2e0d0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
2e0e0 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74  positive if.** t
2e0f0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
2e100 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
2e110 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
2e120 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
2e130 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e  nd.** string. i.
2e140 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
2e150 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
2e160 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e170 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2e180 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2e190 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e1a0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20  ion().** excapt 
2e1b0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
2e1c0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
2e1d0 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
2e1e0 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
2e1f0 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
2e200 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2e210 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
2e220 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
2e230 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
2e240 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
2e250 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2e260 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
2e270 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
2e280 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e290 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
2e2a0 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
2e2b0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a  estroyed when.**
2e2c0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
2e2d0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
2e2e0 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
2e2f0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
2e300 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68  nctions.** or wh
2e310 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  en the [sqlite3*
2e320 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
2e330 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  e is closed usin
2e340 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
2e350 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
2e360 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2e370 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66  6603} A successf
2e380 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a  ul call to the.*
2e390 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e3a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e3b0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2e3c0 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  F,D)] interface.
2e3d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
2e3e0 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46  sters function F
2e3f0 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73   as the comparis
2e400 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64  on function used
2e410 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2e420 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74  implement collat
2e430 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61  ion X on [databa
2e440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
2e450 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2e460 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e   databases havin
2e470 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a  g encoding E..**
2e480 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c  .** {F16604} SQL
2e490 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20  ite understands 
2e4a0 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
2e4b0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
2e4c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e4d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2e4e0 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a  E,P,F,D)] as a z
2e4f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2e500 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
2e510 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68   string in which
2e520 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64   case is ignored
2e530 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61   for ASCII chara
2e540 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20  cters and.**    
2e550 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69        is signifi
2e560 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43  cant for non-ASC
2e570 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  II characters..*
2e580 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75  *.** {F16606} Su
2e590 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74  ccessive calls t
2e5a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2e5b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2e5c0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
2e5d0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
2e5e0 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f  e same values fo
2e5f0 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f  r B, X, and E, o
2e600 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61  verride prior va
2e610 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
2e620 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e   of P, F, and D.
2e630 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20  .**.** {F16609} 
2e640 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  The destructor D
2e650 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
2e660 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e670 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
2e680 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
2e690 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69  t NULL then it i
2e6a0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72  s called with ar
2e6b0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68  gument P when th
2e6c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2e6d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e6e0 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53   is dropped by S
2e6f0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  QLite..**.** {F1
2e700 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6612} A collatin
2e710 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
2e720 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73  opped when it is
2e730 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
2e740 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f  ** {F16615} A co
2e750 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e760 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e   is dropped when
2e770 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2e780 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
2e790 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75       is closed u
2e7a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
2e7b0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ose()]..**.** {F
2e7c0 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74  16618} The point
2e7d0 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33  er P in [sqlite3
2e7e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e7f0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2e800 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2e810 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2e820 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
2e830 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
2e840 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
2e850 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46        function F
2e860 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75   for all subsequ
2e870 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
2e880 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  of F..**.** {F16
2e890 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b  621} A call to [
2e8a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e8b0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
2e8c0 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a  ,F)] is exactly.
2e8d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2e8e0 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74  same as a call t
2e8f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2e900 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2e910 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  ] with.**       
2e920 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61     the same para
2e930 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c  meters and a NUL
2e940 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a  L destructor..**
2e950 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c  .** {F16624} Fol
2e960 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65  lowing a [sqlite
2e970 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e980 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2e990 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2e9a0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2e9b0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
2e9c0 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74  tion F for all t
2e9d0 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  ext comparison.*
2e9e0 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61  *          opera
2e9f0 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61  tions on [databa
2ea00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
2ea10 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20   on text values 
2ea20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2ea30 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69   use the collati
2ea40 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  ng sequence name
2ea50 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32   X..**.** {F1662
2ea60 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2ea70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ea80 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77  16(B,X,E,P,F)] w
2ea90 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a  orks the same.**
2eaa0 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
2eab0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2eac0 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
2ead0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
2eae0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2eaf0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20  ollation name X 
2eb00 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  is understood as
2eb10 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2eb20 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2eb30 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64           instead
2eb40 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   of UTF-8..**.**
2eb50 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d   {F16630} When m
2eb60 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73  ultiple comparis
2eb70 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  on functions are
2eb80 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74   available for t
2eb90 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
2eba0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
2ebb0 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63  quence, SQLite c
2ebc0 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77  hooses the one w
2ebd0 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69  hose text encodi
2ebe0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ng.**          r
2ebf0 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
2ec00 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76  t amount of conv
2ec10 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20  ersion from the 
2ec20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
2ec30 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e      text encodin
2ec40 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
2ec50 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2ec60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ec70 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2ec80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ec90 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2eca0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2ecb0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2ecc0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2ecd0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2ece0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
2ecf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ed00 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
2ed10 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2ed20 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2ed30 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2ed40 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2ed50 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2ed60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ed70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ed80 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2ed90 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2eda0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2edb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2edc0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2edd0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2ede0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2edf0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2ee00 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2ee10 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2ee20 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2ee30 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2ee40 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
2ee50 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
2ee60 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a  ks {F16700}.**.*
2ee70 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
2ee80 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2ee90 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2eea0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2eeb0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2eec0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2eed0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2eee0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2eef0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2ef00 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
2ef10 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
2ef20 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
2ef30 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
2ef40 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71  quence is.** req
2ef50 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
2ef60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2ef70 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2ef80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2ef90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2efa0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
2efb0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
2efc0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
2efd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2efe0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
2eff0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
2f000 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66  F-8. {F16703} If
2f010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f020 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2f030 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73   used, the names
2f040 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61  .** are passed a
2f050 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2f060 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2f070 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f  order. A call to
2f080 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74   either.** funct
2f090 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
2f0a0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
2f0b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
2f0c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2f0d0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2f0e0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2f0f0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2f100 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2f110 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2f120 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f130 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2f140 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f150 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2f160 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2f170 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2f180 68 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69  handle.  The thi
2f190 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
2f1a0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
2f1b0 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
2f1c0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2f1d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
2f1e0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
2f1f0 73 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20  st.** desirable 
2f200 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
2f210 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66  ation sequence f
2f220 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
2f230 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  ..** The fourth 
2f240 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f250 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2f260 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2f270 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
2f280 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2f290 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
2f2a0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
2f2b0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
2f2c0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2f2d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2f2e0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
2f2f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2f300 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2f310 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2f320 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
2f330 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f340 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20  *.** {F16702} A 
2f350 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2f360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
2f370 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50  ation_needed(D,P
2f380 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,F)].**         
2f390 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or [sqlite3_col
2f3a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2f3b0 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a  D,P,F)] causes.*
2f3c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2f3d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f3e0 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65  ion] D to invoke
2f3f0 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68   callback F with
2f400 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
2f410 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77     parameter P w
2f420 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73  henever it needs
2f430 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75   a comparison fu
2f440 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20  nction for a.** 
2f450 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
2f460 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74  ng sequence that
2f470 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f   it does not kno
2f480 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b  w about..**.** {
2f490 46 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63  F16704} Each suc
2f4a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2f4b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2f4c0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a  on_needed()] or.
2f4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2f4e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f4f0 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72  eeded16()] overr
2f500 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ides the callbac
2f510 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  k registered.** 
2f520 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
2f530 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2f540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72  onnection] by pr
2f550 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74  ior calls to eit
2f560 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
2f570 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2f580 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61   {F16706} The na
2f590 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  me of the reques
2f5a0 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ted collating fu
2f5b0 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e  nction passed in
2f5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f5d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2f5e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2f5f0 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68  s in UTF-8 if th
2f600 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
2f610 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73         was regis
2f620 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
2f630 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f640 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  eeded()] and.** 
2f650 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55           is in U
2f660 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2f670 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63  e order if the c
2f680 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20  allback was.**  
2f690 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2f6a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2f6b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f6c0 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a  ed16()]..**.** .
2f6d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2f6e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2f6f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2f700 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
2f710 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2f720 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2f730 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
2f740 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2f750 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
2f760 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2f770 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
2f780 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2f790 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2f7a0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2f7b0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2f7c0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2f7d0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2f7e0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2f7f0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2f800 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2f810 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2f820 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2f830 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2f840 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2f850 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2f860 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2f870 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2f880 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2f890 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2f8a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2f8b0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2f8c0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2f8d0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2f8e0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2f8f0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2f900 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2f910 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2f920 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2f930 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2f940 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2f950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2f960 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2f970 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2f980 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2f990 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2f9a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2f9b0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2f9c0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2f9d0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2f9e0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2f9f0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2fa00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2fa10 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2fa20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2fa30 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2fa40 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2fa50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2fa60 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2fa70 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2fa80 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2fa90 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65  CAPI3REF:  Suspe
2faa0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2fab0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46   A Short Time {F
2fac0 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10530}.**.** The
2fad0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2fae0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75   function.** cau
2faf0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2fb00 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2fb10 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2fb20 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2fb30 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2fb40 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2fb50 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2fb60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
2fb70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2fb80 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2fb90 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2fba0 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  ith .** millisec
2fbb0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2fbc0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2fbd0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2fbe0 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65  ed up to .** the
2fbf0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
2fc00 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
2fc10 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2fc20 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a  leep actually .*
2fc30 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
2fc40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2fc50 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
2fc60 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
2fc70 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2fc80 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2fc90 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2fca0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2fcb0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2fcc0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2fcd0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2fce0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33  S:.**.** {F10533
2fcf0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
2fd00 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
2fd10 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  ce invokes the x
2fd20 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20  Sleep.**        
2fd30 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20    method of the 
2fd40 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2fd50 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64  _vfs|VFS] in ord
2fd60 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
2fd70 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74    suspend execut
2fd80 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
2fd90 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74  nt thread for at
2fda0 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20   least.**       
2fdb0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64     M millisecond
2fdc0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36  s..**.** {F10536
2fdd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
2fde0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
2fdf0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2fe00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
2fe10 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64       millisecond
2fe20 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2fe30 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66  lly requested of
2fe40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a   the operating.*
2fe50 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65  *          syste
2fe60 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  m, which might b
2fe70 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
2fe80 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a  e parameter M..*
2fe90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2fea0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2feb0 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
2fec0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
2fed0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
2fee0 20 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a   Files {F10310}.
2fef0 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
2ff00 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
2ff10 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2ff20 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
2ff30 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
2ff40 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
2ff50 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2ff60 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2ff70 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2ff80 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
2ff90 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
2ffa0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
2ffb0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2ffc0 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  .** is NULL poin
2ffd0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
2ffe0 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66   does a search f
2fff0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
30000 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66  e temporary.** f
30010 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
30020 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
30030 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
30040 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
30050 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
30060 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65  ection.** has be
30070 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
30080 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
30090 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
300a0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
300b0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
300c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
300d0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
300e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
300f0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
30100 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
30110 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
30120 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
30130 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
30140 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
30150 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
30160 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
30170 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
30180 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75  atabase Is In Au
30190 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
301a0 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12930}.**.** Th
301b0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
301c0 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
301d0 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e 6f  faces returns no
301e0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
301f0 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
30200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30210 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
30220 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
30230 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
30240 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69  ely.   Autocommi
30250 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20  t mode is on.** 
30260 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74  by default.  Aut
30270 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
30280 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
30290 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
302a0 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
302b0 6f 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65 64  ode is reenabled
302c0 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
302d0 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
302e0 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
302f0 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
30300 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
30310 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
30320 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
30330 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
30340 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
30350 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
30360 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
30370 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
30380 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
30390 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
303a0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
303b0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
303c0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
303d0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
303e0 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
303f0 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
30400 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
30410 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
30420 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
30430 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
30440 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
30450 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
30460 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
30470 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31  S:.**.** {F12931
30480 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
30490 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29  et_autocommit(D)
304a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
304b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
304c0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
304d0 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   if the [databas
304e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
304f0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
30500 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20  autocommit.**   
30510 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73         mode, res
30520 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
30530 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f   {F12932} Autoco
30540 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
30550 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
30560 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63  * {F12933} Autoc
30570 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
30580 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  sabled by a succ
30590 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73  essful [BEGIN] s
305a0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
305b0 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {F12934} Autocom
305c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  mit mode is enab
305d0 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
305e0 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  ful [COMMIT] or 
305f0 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20  [ROLLBACK].**   
30600 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
30610 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ..** .**.** LIMI
30620 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20  TATIONS:.***.** 
30630 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {U12936} If anot
30640 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
30650 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
30660 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
30670 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
30680 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
30690 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
306a0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
306b0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
306c0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
306d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
306e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
306f0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
30700 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
30710 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
30720 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
30730 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
30740 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31   Statement {F131
30750 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20}.**.** The sq
30760 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
30770 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
30780 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65  urns the [sqlite
30790 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
307a0 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
307b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
307c0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
307d0 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  ** The database 
307e0 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20  handle returned 
307f0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
30800 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73  ndle.** is the s
30810 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
30820 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
30830 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
30840 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
30850 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30860 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
30870 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
30880 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
30890 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
308a0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
308b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
308c0 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54  **.** {F13123} T
308d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
308e0 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
308f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30900 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
30910 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
30920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
30930 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
30940 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
30950 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30960 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
30970 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
30980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30990 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
309a0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
309b0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
309c0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
309d0 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
309e0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
309f0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
30a00 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
30a10 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
30a20 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
30a30 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
30a40 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
30a50 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
30a60 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
30a70 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
30a80 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30a90 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
30aa0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
30ab0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
30ac0 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
30ad0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
30ae0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
30af0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
30b00 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
30b10 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
30b20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
30b30 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
30b40 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
30b50 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
30b60 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
30b70 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30b80 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
30b90 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
30ba0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
30bb0 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
30bc0 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
30bd0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
30be0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
30bf0 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  k.  If the callb
30c00 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
30c10 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  hook function .*
30c20 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
30c30 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ro, then the com
30c40 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
30c50 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
30c60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
30c70 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
30c80 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
30c90 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
30ca0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
30cb0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
30cc0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
30cd0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  d..**.** Registe
30ce0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
30cf0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
30d00 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
30d10 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
30d20 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
30d30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30d40 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
30d50 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  en .** rolled ba
30d60 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
30d70 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
30d80 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
30d90 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
30da0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
30db0 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
30dc0 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
30dd0 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
30de0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
30df0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
30e00 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
30e10 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
30e20 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
30e30 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
30e40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30e50 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
30e60 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
30e70 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
30e80 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
30e90 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
30ea0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
30eb0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
30ec0 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
30ed0 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
30ee0 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
30ef0 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  o>.**.** These a
30f00 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  re experimental 
30f10 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61  interfaces and a
30f20 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
30f30 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ange..**.** INVA
30f40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30f50 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
30f60 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
30f70 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
30f80 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
30f90 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
30fa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
30fb0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
30fc0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
30fd0 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
30fe0 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
30ff0 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74   commits on [dat
31000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31010 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
31020 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  52} The [sqlite3
31030 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
31040 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
31050 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
31060 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
31070 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
31080 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
31090 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20  e same .**      
310a0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
310b0 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f  nnection ] D , o
310c0 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
310d0 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
310e0 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
310f0 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20  cular [database 
31100 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
31110 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
31120 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
31130 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
31140 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
31150 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
31160 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
31170 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
31180 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
31190 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
311a0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
311b0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
311c0 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
311d0 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
311e0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
311f0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65  back is cancelle
31200 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
31210 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
31220 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
31230 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
31240 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  its..**.** {F129
31250 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69  55} If the commi
31260 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
31270 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e  ns non-zero then
31280 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a   the commit is.*
31290 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65  *          conve
312a0 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
312b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
312c0 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  961} The [sqlite
312d0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
312e0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
312f0 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
31300 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
31310 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
31320 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
31330 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
31340 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
31350 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
31360 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b   rolls back on [
31370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31380 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
31390 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69  12962} The [sqli
313a0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
313b0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
313c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
313d0 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
313e0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
313f0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
31400 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
31410 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
31420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
31430 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
31440 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
31450 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
31460 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
31470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31480 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36   D..**.** {F1296
31490 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
314a0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
314b0 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  k_hook()] overwr
314c0 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
314d0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
314e0 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
314f0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
31500 46 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46  F12964} If the F
31510 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
31520 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
31530 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
31540 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
31550 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63  then the rollbac
31560 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  k hook callback 
31570 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64  is cancelled and
31580 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
31590 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
315a0 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
315b0 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63  action rolls bac
315c0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  k..*/.void *sqli
315d0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
315e0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
315f0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
31600 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
31610 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
31620 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
31630 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
31640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31650 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
31660 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
31670 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a  cks {F12970}.**.
31680 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
31690 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
316a0 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74  erface.** regist
316b0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
316c0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
316d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
316e0 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
316f0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74  by the .** first
31700 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20   argument to be 
31710 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
31720 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
31730 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
31740 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  eleted..** Any c
31750 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
31760 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31770 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
31780 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a  for the same .**
31790 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
317a0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
317b0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
317c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
317d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
317e0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
317f0 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20  voke when a .** 
31800 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
31810 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
31820 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72  ted. .** The fir
31830 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
31840 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
31850 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
31860 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
31870 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
31880 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
31890 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
318a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
318b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
318c0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
318d0 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49  DELETE] or [SQLI
318e0 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64  TE_UPDATE],.** d
318f0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
31900 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
31910 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
31920 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ck to be invoked
31930 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
31940 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  nd .** fourth ar
31950 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
31960 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
31970 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
31980 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a  database and .**
31990 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
319a0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
319b0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
319c0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
319d0 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20  arameter is .** 
319e0 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
319f0 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20   row..** In the 
31a00 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
31a10 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72  e, this is the r
31a20 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74  owid after .** t
31a30 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
31a40 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
31a50 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
31a60 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31a70 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
31a80 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
31a90 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
31aa0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
31ab0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
31ac0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
31ad0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
31ae0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
31af0 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
31b00 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75  value.** is retu
31b10 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
31b20 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
31b30 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
31b40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
31b50 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
31b60 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
31b70 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,P)] interface c
31b80 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  auses callback.*
31b90 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
31ba0 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f  ion F to be invo
31bb0 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20 70  ked with first p
31bc0 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65  arameter P whene
31bd0 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
31be0 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d  a table row is m
31bf0 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
31c00 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e  d, or deleted on
31c10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
31c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31c30 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
31c40 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  973} The [sqlite
31c50 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
31c60 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
31c70 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
31c80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
31c90 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69   P for the previ
31ca0 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20  ous call on the 
31cb0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
31cc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a  onnection] D,.**
31cd0 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
31ce0 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  L for the first 
31cf0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  call..**.** {F12
31d00 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61  975} If the upda
31d10 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
31d20 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75   F in [sqlite3_u
31d30 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
31d40 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
31d50 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
31d60 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  no update callba
31d70 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a  cks are made..**
31d80 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63  .** {F12977} Eac
31d90 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
31da0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
31db0 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73  ,F,P)] overrides
31dc0 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20   prior calls.** 
31dd0 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
31de0 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f  same interface o
31df0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
31e00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31e10 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37   D..**.** {F1297
31e20 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  9} The update ho
31e30 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ok callback is n
31e40 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
31e50 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a  internal system.
31e60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c  **          tabl
31e70 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  es such as sqlit
31e80 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
31e90 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65  ite_sequence are
31ea0 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
31eb0 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 65   {F12981} The se
31ec0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
31ed0 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c  o the update cal
31ee0 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20  lback .**       
31ef0 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51     is one of [SQ
31f00 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
31f10 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
31f20 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
31f30 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  ,.**          de
31f40 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
31f50 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
31f60 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
31f70 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
31f80 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20  .**.** {F12983} 
31f90 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
31fa0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
31fb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
31fc0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a  ontain pointers.
31fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a  **          to z
31fe0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
31ff0 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69  TF-8 strings whi
32000 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73  ch are the names
32010 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
32020 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64      database and
32030 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62   table that is b
32040 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a  eing updated...*
32050 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66  * {F12985} The f
32060 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
32070 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72  rameter is the r
32080 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20  owid of the row 
32090 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  after.**        
320a0 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63    the change occ
320b0 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  urs..*/.void *sq
320c0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
320d0 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
320e0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
320f0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
32100 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
32110 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
32120 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
32130 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
32140 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
32150 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
32160 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10330}.**.**
32170 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
32180 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
32190 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
321a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
321b0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
321c0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
321d0 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63  s between connec
321e0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d  tions to the sam
321f0 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53  e database..** S
32200 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
32210 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
32220 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 69  t is true and di
32230 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
32240 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c  gument.** is fal
32250 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20  se..**.** Cache 
32260 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
32270 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a  ed and disabled.
32280 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ** for an entire
32290 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20   process. {END} 
322a0 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
322b0 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
322c0 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20  rsion 3.5.0..** 
322d0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
322e0 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61  s of SQLite, sha
322f0 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ring was.** enab
32300 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
32310 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
32320 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
32330 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
32340 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
32350 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
32360 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
32370 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
32380 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
32390 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
323a0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
323b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
323c0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
323d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
323e0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
323f0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
32400 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
32410 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
32420 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
32430 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
32440 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
32450 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
32460 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 20 57  hared cache.   W
32470 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
32480 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
32490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
324a0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
324b0 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
324c0 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
324d0 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
324e0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
324f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
32500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
32510 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
32520 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20  ed cache was.** 
32530 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
32540 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  led successfully
32550 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
32560 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
32570 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
32580 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
32590 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
325a0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
325b0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
325c0 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
325d0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
325e0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
325f0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
32600 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
32610 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
32620 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
32630 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32640 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d  .** .** {F10331}
32650 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
32660 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
32670 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
32680 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20  ed_cache(B)].** 
32690 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e           will en
326a0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
326b0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
326c0 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71  e for any subseq
326d0 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  uently.**       
326e0 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61     created [data
326f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32700 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
32710 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  cess..**.** {F10
32720 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64  336} When shared
32730 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
32740 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
32750 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
32760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
32770 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61  erface will alwa
32780 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
32790 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  or..**.** {F1033
327a0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
327b0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
327c0 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63  che(B)] interfac
327d0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
327e0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
327f0 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
32800 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
32810 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
32820 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sfully..**.** {F
32830 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
32840 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
32850 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69  by default..*/.i
32860 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
32870 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
32880 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32890 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54  3REF:  Attempt T
328a0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
328b0 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a  ry {F17340}.**.*
328c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
328d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
328e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
328f0 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62  s to.** free N b
32900 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d  ytes of heap mem
32910 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
32920 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
32930 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  l memory.** allo
32940 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
32950 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62  the database lab
32960 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
32970 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63  ory used.** to c
32980 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61  ache database pa
32990 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
329a0 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
329b0 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e   example of.** n
329c0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
329d0 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65  ory.  Sqlite3_re
329e0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
329f0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32a00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
32a10 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68  tually freed, wh
32a20 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
32a30 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61  e or less.** tha
32a40 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
32a50 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  uested..**.** IN
32a60 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32a70 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71  {F17341} The [sq
32a80 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32a90 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61  mory(N)] interfa
32aa0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a  ce attempts to.*
32ab0 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20  *          free 
32ac0 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
32ad0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
32ae0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
32af0 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tial.**         
32b00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32b10 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20  ons held by the 
32b20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 79  database labrary
32b30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d  ..**.** {F16342}
32b40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32b50 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d  lease_memory(N)]
32b60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32b70 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
32b80 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
32b90 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d  y freed, which m
32ba0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
32bb0 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
32bc0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
32bd0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69   requested..*/.i
32be0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
32bf0 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
32c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32c10 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74    Impose A Limit
32c20 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46   On Heap Size {F
32c30 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17350}.**.** The
32c40 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
32c50 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
32c60 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61  face.** places a
32c70 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
32c80 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
32c90 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
32ca0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
32cb0 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49  .** by SQLite. I
32cc0 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
32cd0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
32ce0 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77  ested .** that w
32cf0 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20  ould exceed the 
32d00 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
32d10 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
32d20 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a  e_memory()] is.*
32d30 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  * invoked one or
32d40 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
32d50 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
32d60 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
32d70 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61  ocation.** is ma
32d80 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  de..**.** The li
32d90 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
32da0 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66  oft", because if
32db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
32dc0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63  ease_memory()] c
32dd0 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75  annot.** free su
32de0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
32df0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
32e00 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
32e10 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
32e20 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
32e30 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
32e40 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
32e50 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
32e60 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
32e70 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
32e80 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
32e90 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
32ea0 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
32eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
32ec0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
32ed0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
32ee0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
32ef0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
32f00 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
32f10 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
32f20 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
32f30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
32f40 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
32f50 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
32f60 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
32f70 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65    .** But if the
32f80 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32f90 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c   cannot honored,
32fa0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
32fb0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
32fc0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
32fd0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
32fe0 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
32ff0 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  t is .** called 
33000 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
33010 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
33020 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
33030 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
33040 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
33050 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
33060 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
33070 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
33080 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
33090 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
330a0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
330b0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
330c0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
330d0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
330e0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
330f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
33100 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
33110 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
33120 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
33130 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
33140 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
33150 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
33160 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
33170 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
33180 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
33190 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
331a0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
331b0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
331c0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
331d0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
331e0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
331f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
33200 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20  .**.** {F16351} 
33210 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  The [sqlite3_sof
33220 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d  t_heap_limit(N)]
33230 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65   interface place
33240 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a  s a soft limit.*
33250 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20  *          of N 
33260 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f  bytes on the amo
33270 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
33280 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
33290 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20  llocated.**     
332a0 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69       using [sqli
332b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
332c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
332d0 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e  c()] at any poin
332e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
332f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   time..**.** {F1
33300 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20  6352} If a call 
33310 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
33320 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
33330 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75  3_realloc()] wou
33340 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ld.**          c
33350 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61  ause the total a
33360 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74  mount of allocat
33370 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63  ed memory to exc
33380 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  eed the.**      
33390 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69      soft heap li
333a0 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  mit, then [sqlit
333b0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
333c0 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  y()] is invoked.
333d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
333e0 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64  n attempt to red
333f0 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75  uce the memory u
33400 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72  sage prior to pr
33410 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20  oceeding.**     
33420 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65       with the me
33430 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33440 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b  attempt..**.** {
33450 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f  F16353} Calls to
33460 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
33470 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33480 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
33490 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20  trigger.**      
334a0 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20      attempts to 
334b0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
334c0 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20  age through the 
334d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
334e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 68  **          mech
334f0 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65  anism continue e
33500 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d  ven if the attem
33510 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d  pt to reduce mem
33520 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
33530 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 65  usage is unsucce
33540 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssful..**.** {F1
33550 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65  6354} A negative
33560 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
33570 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74  or N in a call t
33580 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
33590 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
335a0 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73  _limit(N)] means
335b0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
335c0 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20  o soft.**       
335d0 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e     heap limit an
335e0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  d [sqlite3_relea
335f0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
33600 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20  l only be.**    
33610 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65        called whe
33620 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70  n memory is comp
33630 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 64  letely exhausted
33640 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d  ..**.** {F16355}
33650 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
33660 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
33670 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
33680 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ro..**.** {F1635
33690 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  8} Each call to 
336a0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
336b0 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65  ap_limit(N)] ove
336c0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20  rrides the.**   
336d0 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 65         values se
336e0 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63  t by all prior c
336f0 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alls..*/.void sq
33700 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
33710 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  limit(int);../*.
33720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78  ** CAPI3REF:  Ex
33730 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
33740 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
33750 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30   A Table {F12850
33760 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
33770 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tine.** returns 
33780 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20  meta-data about 
33790 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
337a0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20  n of a specific 
337b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
337c0 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
337d0 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
337e0 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20  n handle passed 
337f0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
33800 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65  ction .** argume
33810 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  nt..**.** The co
33820 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
33830 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
33840 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
33850 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
33860 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69   .** this functi
33870 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
33880 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
33890 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
338a0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
338b0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
338c0 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
338d0 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
338e0 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
338f0 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
33900 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
33910 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
33920 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
33930 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
33940 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
33950 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
33960 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65  algorithm as the
33970 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
33980 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73   uses to .** res
33990 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
339a0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
339b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
339c0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
339d0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
339e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
339f0 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
33a00 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  mn .** name of t
33a10 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
33a20 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33a30 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
33a40 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a  e parameters .**
33a50 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
33a60 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61  .** Meta informa
33a70 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  tion is returned
33a80 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
33a90 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
33aa0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  ons passed as.**
33ab0 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62   the 5th and sub
33ac0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
33ad0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
33ae0 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
33af0 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  e .** arguments 
33b00 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
33b10 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
33b20 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
33b30 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a  ment of meta .**
33b40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
33b50 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommitted..**.** 
33b60 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
33b70 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
33b80 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
33b90 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
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 0a 2a 2a 0a 2a 2a  ----------.**.**
33bc0 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
33bd0 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
33be0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
33bf0 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
33c00 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
33c10 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
33c20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33c30 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
33c40 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
33c50 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
33c60 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
33c70 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
33c80 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
33c90 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
33ca0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
33cb0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
33cc0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
33cd0 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
33ce0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
33cf0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
33d00 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
33d10 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
33d20 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
33d30 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
33d40 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
33d50 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
33d60 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
33d70 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
33d80 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
33d90 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
33da0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
33db0 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
33dc0 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
33dd0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33de0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
33df0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
33e00 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
33e10 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
33e20 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
33e30 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
33e40 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
33e50 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
33e60 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
33e70 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
33e80 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
33e90 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
33ea0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
33eb0 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
33ec0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
33ed0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
33ee0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
33ef0 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
33f00 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
33f10 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
33f20 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
33f30 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
33f40 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
33f50 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
33f60 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
33f70 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
33f80 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
33f90 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
33fa0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
33fb0 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
33fc0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
33fd0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
33fe0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
33ff0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
34000 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
34010 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
34020 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
34030 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
34040 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
34050 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
34060 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
34070 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
34080 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
34090 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
340a0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
340b0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
340c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
340d0 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
340e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
340f0 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
34100 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
34110 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
34120 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
34130 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
34140 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
34150 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
34160 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
34170 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
34180 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
34190 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
341a0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
341b0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
341c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
341d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
341e0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
341f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
34200 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
34210 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34220 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
34230 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
34240 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
34250 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
34260 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34270 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
34280 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
34290 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
342a0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
342b0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
342c0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
342d0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
342e0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
342f0 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
34300 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
34310 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
34320 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
34330 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
34340 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
34350 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
34360 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
34370 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
34380 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
34390 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
343a0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
343b0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
343c0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
343d0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
343e0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
343f0 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
34400 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
34410 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
34420 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
34430 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
34440 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
34450 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
34460 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
34470 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
34480 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
34490 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
344a0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
344b0 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
344c0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
344d0 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
344e0 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
344f0 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
34500 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
34510 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
34520 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
34530 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
34540 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
34550 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
34560 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
34570 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
34580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
34590 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
345a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
345b0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
345c0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
345d0 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
345e0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
345f0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
34600 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
34610 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
34620 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
34630 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
34640 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
34650 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
34660 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
34670 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
34680 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
34690 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
346a0 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
346b0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
346c0 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
346d0 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
346e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
346f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
34700 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
34710 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
34720 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
34730 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
34740 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
34750 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
34760 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
34770 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
34780 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
34790 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
347a0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
347b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
347c0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
347d0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
347e0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
347f0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
34800 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
34810 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
34820 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
34830 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
34840 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
34850 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
34860 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
34870 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
34880 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
34890 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
348a0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
348b0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
348c0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
348d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
348e0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
348f0 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
34900 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
34910 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
34920 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
34930 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
34940 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
34950 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
34960 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
34970 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
34980 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
34990 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
349a0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
349b0 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
349c0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
349d0 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
349e0 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
349f0 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
34a00 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
34a10 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
34a20 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
34a30 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
34a40 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
34a50 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
34a60 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
34a70 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
34a80 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
34a90 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
34aa0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
34ab0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
34ac0 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
34ad0 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
34ae0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
34af0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
34b00 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
34b10 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
34b20 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
34b30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
34b40 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
34b50 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
34b60 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
34b70 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
34b80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
34b90 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
34ba0 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
34bb0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
34bc0 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
34bd0 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
34be0 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
34bf0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
34c00 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65  invoked.** whene
34c10 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  ver a new databa
34c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34c30 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
34c40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
34c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
34c60 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
34c70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b  e3_open_v2()]. {
34c80 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
34c90 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
34ca0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
34cb0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
34cc0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
34cd0 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
34ce0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
34cf0 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
34d00 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
34d10 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
34d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
34d30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d  ..**.** {F12642}
34d40 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
34d50 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
34d60 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
34d70 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
34d80 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
34d90 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
34da0 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
34db0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d  ..**.** {F12643}
34dc0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
34dd0 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
34de0 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
34df0 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
34e00 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
34e10 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c  from sqlite_mall
34e20 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79  oc(). {END} If y
34e30 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20  ou run a memory 
34e40 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20  leak.** checker 
34e50 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20  on your program 
34e60 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61  and it reports a
34e70 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66   leak because of
34e80 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20   this.** array, 
34e90 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  then invoke [sql
34ea0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
34eb0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
34ec0 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
34ed0 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
34ee0 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mory..**.** {F12
34ef0 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
34f00 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
34f10 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
34f20 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
34f30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
34f40 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
34f50 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
34f60 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
34f70 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
34f80 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
34f90 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
34fa0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34fb0 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
34fc0 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
34fd0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
34fe0 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
34ff0 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36  n Loading {F1266
35000 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31  0}.**.** {F12661
35010 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
35020 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
35030 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
35040 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  ed.** automatic 
35050 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
35060 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  }  This.** routi
35070 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
35080 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
35090 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  r [sqlite3_auto_
350a0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
350b0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
350c0 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20  2662} This call 
350d0 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74  disabled automat
350e0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
350f0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
35100 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ND}.**.** This i
35110 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
35120 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
35130 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
35140 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
35150 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
35160 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
35170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35180 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
35190 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
351a0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
351b0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
351c0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
351d0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
351e0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
351f0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
35200 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
35210 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
35220 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
35230 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
35240 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
35250 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
35260 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
35270 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
35280 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
35290 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
352a0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
352b0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
352c0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
352d0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
352e0 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
352f0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
35300 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
35310 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
35320 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
35330 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
35340 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
35350 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
35360 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
35370 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
35380 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
35390 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
353a0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
353b0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
353c0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
353d0 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
353e0 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
353f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35400 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
35410 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
35420 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35430 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
35440 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
35450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35460 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
35470 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a  ject {F18000}.**
35480 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
35490 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20  e3_module.**.** 
354a0 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c  A module is a cl
354b0 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74  ass of virtual t
354c0 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64  ables.  Each mod
354d0 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a  ule is defined.*
354e0 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65  * by an instance
354f0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
35500 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  g structure.  Th
35510 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
35520 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20  sists.** mostly 
35530 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
35540 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74  he module..*/.st
35550 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
35560 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
35570 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
35580 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
35590 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
355a0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
355b0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
355c0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
355d0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
355e0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
355f0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
35600 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
35610 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
35620 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
35630 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
35640 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
35650 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
35660 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
35670 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
35680 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
35690 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
356a0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
356b0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
356c0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
356d0 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
356e0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
356f0 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
35700 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35710 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35720 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
35730 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
35740 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
35750 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
35760 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
35770 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35780 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
35790 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
357a0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
357b0 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
357c0 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
357d0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
357e0 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
357f0 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
35800 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
35810 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
35820 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
35830 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35840 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
35850 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
35860 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
35870 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35880 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
35890 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
358a0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
358b0 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
358c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
358d0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
358e0 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
358f0 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
35900 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
35910 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
35920 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35930 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
35940 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35950 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35960 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
35970 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35980 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
35990 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
359a0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
359b0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
359c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
359d0 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
359e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
359f0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35a00 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
35a10 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
35a20 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35a30 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35a50 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
35a60 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52  rg);..  int (*xR
35a70 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  ename)(sqlite3_v
35a80 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73  tab *pVtab, cons
35a90 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d  t char *zNew);.}
35aa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35ab0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
35ac0 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d   Indexing Inform
35ad0 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a 2a  ation {F18100}.*
35ae0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
35af0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
35b00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35b10 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
35b20 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
35b30 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
35b40 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
35b50 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
35b60 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
35b70 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78  reply from the x
35b80 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74  BestIndex.** met
35b90 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  hod of an sqlite
35ba0 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66  3_module.  The f
35bb0 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
35bc0 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
35bd0 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
35be0 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
35bf0 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
35c00 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
35c10 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
35c20 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
35c30 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
35c40 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
35c50 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
35c60 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
35c70 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a  straints of the.
35c80 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20  ** form:.**.**  
35c90 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50         column OP
35ca0 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72   expr.**.** Wher
35cb0 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
35cc0 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
35cd0 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65   &gt;=.  .** The
35ce0 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
35cf0 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a  ator is stored.*
35d00 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  * in aConstraint
35d10 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
35d20 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
35d30 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a  is stored in .**
35d40 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
35d50 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
35d60 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
35d70 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
35d80 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
35d90 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
35da0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
35db0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
35dc0 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
35dd0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
35de0 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
35df0 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
35e00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
35e10 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
35e20 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
35e30 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
35e40 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
35e50 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
35e60 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
35e70 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
35e80 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
35e90 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
35ea0 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
35eb0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
35ec0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
35ed0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
35ee0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
35ef0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
35f00 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
35f10 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
35f20 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
35f30 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
35f40 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
35f50 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
35f60 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
35f70 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
35f80 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
35f90 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
35fa0 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
35fb0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
35fc0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
35fd0 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
35fe0 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  ** The xBestInde
35ff0 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  x method must fi
36000 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
36010 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
36020 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
36030 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
36040 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
36050 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65  er.  If argvInde
36060 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
36070 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
36080 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
36090 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
360a0 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
360b0 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
360c0 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
360d0 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
360e0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
360f0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
36100 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
36110 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
36120 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
36130 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
36140 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
36150 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
36160 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
36170 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
36180 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
36190 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
361a0 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
361b0 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a   into xFilter..*
361c0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  * sqlite3_free()
361d0 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
361e0 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54   idxPtr if needT
361f0 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
36200 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
36210 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
36220 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
36230 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69   from xFilter wi
36240 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
36250 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
36260 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
36270 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
36280 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
36290 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
362a0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
362b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
362c0 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
362d0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
362e0 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
362f0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
36300 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
36310 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
36320 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
36330 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
36340 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
36350 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
36360 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
36370 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
36380 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
36390 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
363a0 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
363b0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
363c0 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
363d0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
363e0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
363f0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
36400 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
36410 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
36420 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36430 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
36440 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
36450 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36460 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
36470 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
36480 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
36490 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
364a0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
364b0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
364c0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
364d0 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
364e0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
364f0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
36500 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
36510 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
36520 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
36530 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
36540 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
36550 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
36560 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
36570 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
36580 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
36590 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
365a0 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
365b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
365c0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
365d0 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
365e0 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
365f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36600 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
36610 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
36620 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
36630 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
36640 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
36650 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
36660 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
36670 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
36680 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
36690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
366a0 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
366b0 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75  ause */..  /* Ou
366c0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
366d0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
366e0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
366f0 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
36700 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
36710 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
36720 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
36730 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
36740 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
36750 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
36760 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
36770 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
36780 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
36790 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
367a0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
367b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
367c0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
367d0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
367e0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
367f0 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
36800 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
36810 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
36820 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
36830 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
36840 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
36850 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
36860 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
36870 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
36880 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
36890 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
368a0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
368b0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
368c0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
368d0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
368e0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
368f0 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
36900 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
36910 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
36920 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36930 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
36940 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36950 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
36960 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
36970 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36980 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
36990 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
369a0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
369b0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
369c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
369d0 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
369e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
369f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
36a00 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
36a10 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
36a20 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
36a30 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
36a40 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F18200}.**.** T
36a50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
36a60 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
36a70 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d  a new module nam
36a80 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65  e with an SQLite
36a90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
36aa0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
36ab0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
36ac0 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67   before creating
36ad0 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20   new.** virtual 
36ae0 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f  tables on the mo
36af0 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
36b00 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e  using preexistin
36b10 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  g virtual.** tab
36b20 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  les of the modul
36b30 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
36b40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
36b50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36b70 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
36b80 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
36b90 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
36ba0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
36bb0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
36bc0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
36bd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
36be0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
36bf0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
36c00 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
36c10 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20  void *          
36c20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
36c30 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
36c40 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
36c50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36c60 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
36c70 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36c80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46  mplementation {F
36c90 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  18210}.**.** Thi
36ca0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
36cb0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
36cc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36cd0 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
36ce0 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
36cf0 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
36d00 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
36d10 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
36d20 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
36d30 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
36d40 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
36d50 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
36d60 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
36d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36d80 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
36d90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36da0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
36db0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
36dc0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
36dd0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
36de0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
36df0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
36e00 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
36e10 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
36e20 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
36e30 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
36e40 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
36e50 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
36e60 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
36e70 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
36e80 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
36e90 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
36ea0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
36eb0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
36ec0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
36ed0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36ee0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36ef0 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b  nstance Object {
36f00 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F18010}.** KEYWO
36f10 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
36f20 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  b.**.** Every mo
36f30 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
36f40 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
36f50 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
36f60 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
36f70 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  * to describe a 
36f80 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
36f90 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  nce of the modul
36fa0 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  e.  Each subclas
36fb0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
36fc0 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
36fd0 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
36fe0 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
36ff0 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a  entation.   The.
37000 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  ** purpose of th
37010 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
37020 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
37030 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
37040 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20  re common.** to 
37050 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
37060 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
37070 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
37080 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74   methods can set
37090 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
370a0 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61  e by assigning a
370b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69  .** string obtai
370c0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
370d0 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45  _mprintf() to zE
370e0 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
370f0 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
37100 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
37110 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
37120 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
37130 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
37140 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ).** prior to as
37150 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
37160 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
37170 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f    After the erro
37180 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20  r message.** is 
37190 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20  delivered up to 
371a0 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69  the client appli
371b0 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69  cation, the stri
371c0 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ng will be autom
371d0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65  atically.** free
371e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65  d by sqlite3_fre
371f0 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72  e() and the zErr
37200 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62  Msg field will b
37210 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a  e zeroed.  Note.
37220 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  ** that sqlite3_
37230 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
37240 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65  lite3_free() are
37250 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72   used on the zEr
37260 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69  rMsg field.** si
37270 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nce virtual tabl
37280 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20  es are commonly 
37290 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c  implemented in l
372a0 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
372b0 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e  ns which.** do n
372c0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74  ot have access t
372d0 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66  o sqlite3MPrintf
372e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65  () or sqlite3Fre
372f0 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  e()..*/.struct s
37300 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
37310 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
37320 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
37330 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
37340 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
37350 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
37360 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
37370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
37380 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a  d internally */.
37390 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
373a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
373b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
373c0 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
373d0 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
373e0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
373f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37400 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
37410 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
37420 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
37430 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
37440 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
37450 20 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32 30   Object  {F18020
37460 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  }.** KEYWORDS: s
37470 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
37480 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d  or.**.** Every m
37490 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
374a0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
374b0 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c  lass of the foll
374c0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a  owing structure.
374d0 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  ** to describe c
374e0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
374f0 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75  t into the virtu
37500 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65  al table and are
37510 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
37520 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
37530 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
37540 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
37550 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f   using the.** xO
37560 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
37570 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
37580 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
37590 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e  ation will defin
375a0 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  e.** the content
375b0 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72   of a cursor str
375c0 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69  ucture to suit i
375d0 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a  ts own needs..**
375e0 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c  .** This supercl
375f0 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72  ass exists in or
37600 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69  der to define fi
37610 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73  elds of the curs
37620 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  or that.** are c
37630 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70  ommon to all imp
37640 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f  lementations..*/
37650 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
37660 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
37670 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37680 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
37690 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
376a0 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
376b0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
376c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
376d0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
376e0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
376f0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
37700 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
37710 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
37720 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
37730 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a 2a  e {F18280}.**.**
37740 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64   The xCreate and
37750 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
37760 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73  s of a module us
37770 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
37780 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  API.** to declar
37790 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
377a0 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
377b0 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
377c0 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
377d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
377e0 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
377f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
37800 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
37810 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
37820 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
37830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37840 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
37850 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
37860 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30 30  al Table {F18300
37870 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  }.**.** Virtual 
37880 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
37890 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
378a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
378b0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
378c0 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75  sing the xFindFu
378d0 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20  nction method.  
378e0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
378f0 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
37900 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
37910 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
37920 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   be overloaded..
37930 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d  **.** This API m
37940 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
37950 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
37960 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
37970 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
37980 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
37990 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
379a0 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
379b0 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
379c0 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
379d0 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
379e0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
379f0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d  created.  The im
37a00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
37a10 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
37a20 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
37a30 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
37a40 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
37a50 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
37a60 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
37a70 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
37a80 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
37a90 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
37aa0 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68   to be a place-h
37ab0 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
37ac0 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
37ad0 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74  oaded.** by virt
37ae0 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a  ual tables..**.*
37af0 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c  * This API shoul
37b00 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20  d be considered 
37b10 70 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74  part of the virt
37b20 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
37b30 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73  ace,.** which is
37b40 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
37b50 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  d subject to cha
37b60 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
37b70 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
37b80 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
37b90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
37ba0 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
37bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
37bc0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
37bd0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
37be0 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
37bf0 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
37c00 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
37c10 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
37c20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
37c30 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
37c40 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
37c50 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
37c60 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
37c70 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
37c80 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
37c90 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
37ca0 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
37cb0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
37cc0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
37cd0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
37ce0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
37cf0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
37d00 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
37d10 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
37d20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
37d30 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
37d40 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
37d50 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
37d60 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  t..**.****** EXP
37d70 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
37d80 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
37d90 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
37da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a  ***********.*/..
37db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37dc0 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
37dd0 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 30  pen BLOB {F17800
37de0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
37df0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
37e00 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
37e10 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
37e20 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  ich.** increment
37e30 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70 72  al I/O can be pr
37e40 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65  eformed..** Obje
37e50 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
37e60 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 0a   are created by.
37e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
37e80 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73  _open()] and des
37e90 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
37ea0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
37eb0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
37ec0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
37ed0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
37ee0 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
37ef0 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
37f00 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
37f10 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
37f20 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c  ctions of the bl
37f30 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  ob..** The [sqli
37f40 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
37f50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
37f60 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
37f70 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
37f80 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
37f90 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
37fa0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
37fb0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
37fc0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
37fd0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
37fe0 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a  I/O {F17810}.**.
37ff0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
38000 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c  es opens a handl
38010 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f  e to the blob lo
38020 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
38030 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f  iRow, column zCo
38040 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62  lumn, table zTab
38050 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
38060 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20  Db;.** in other 
38070 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d 65  words,  the same
38080 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64   blob that would
38090 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
380a0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
380b0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
380c0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
380d0 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  le WHERE rowid =
380e0 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
380f0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
38100 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
38110 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
38120 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65   the blob is ope
38130 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64  ned for .** read
38140 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73   and write acces
38150 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f  s. If it is zero
38160 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70  , the blob is op
38170 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a  ened for read .*
38180 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  * access..**.** 
38190 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
381a0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
381b0 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
381c0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
381d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
381e0 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
381f0 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
38200 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
38210 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77  ** is assigned w
38220 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
38230 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
38240 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
38250 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   For the main da
38260 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
38270 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
38280 73 20 22 6d 61 69 6e 22 2e 20 20 46 6f 72 0a 2a  s "main".  For.*
38290 2a 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  * TEMP tables, t
382a0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
382b0 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
382c0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
382d0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
382e0 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
382f0 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  w .** [sqlite3_b
38300 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
38310 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  e] is written to
38320 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74   *ppBlob. .** Ot
38330 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
38340 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
38350 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
38360 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
38370 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
38380 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
38390 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73   caller..** This
383a0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
383b0 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
383c0 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
383d0 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
383e0 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
383f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
38400 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
38410 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49  msg()]..** .** I
38420 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38430 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63   {F17813} A succ
38440 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
38450 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
38460 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c  3_blob_open(D,B,
38470 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20  T,C,R,F,P)].**  
38480 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
38490 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c 69  e opens an [sqli
384a0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
384b0 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a 2a   P on the blob.*
384c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f  *          in co
384d0 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 20  lumn C of table 
384e0 54 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 20  T in database B 
384f0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
38500 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
38510 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 63  * {F17814} A suc
38520 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
38530 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
38540 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d  lob_open(D,...)]
38550 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 20   starts.**      
38560 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61      a new transa
38570 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 61  ction on [databa
38580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
38590 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 74   if that connect
385a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
385b0 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69  is not already i
385c0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  n a transaction.
385d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d 20  .**.** {F17816} 
385e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
385f0 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52  b_open(D,B,T,C,R
38600 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
38610 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 0a   opens the blob.
38620 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
38630 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
38640 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c  ccess if and onl
38650 79 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d  y if the F param
38660 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
38670 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a   is non-zero..**
38680 0a 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68 65  .** {F17819} The
38690 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
386a0 70 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  pen()] interface
386b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
386c0 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20 20  _OK] on .**     
386d0 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64       success and
386e0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
386f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
38700 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
38710 46 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72  F17821} If an er
38720 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
38730 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  g evaluation of 
38740 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
38750 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  en(D,...)].**   
38760 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73         then subs
38770 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
38780 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
38790 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (D)],.**        
387a0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
387b0 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  g(D)], and [sqli
387c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
387d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
387e0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
387f0 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20  tion approprate 
38800 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a  for that error..
38810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
38820 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
38830 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
38840 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
38850 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
38860 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
38870 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
38880 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
38890 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
388a0 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
388b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
388c0 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c  REF:  Close A BL
388d0 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33  OB Handle {F1783
388e0 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61  0}.**.** Close a
388f0 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  n open [sqlite3_
38900 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64  blob | blob hand
38910 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69  le]..**.** Closi
38920 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20  ng a BLOB shall 
38930 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e  cause the curren
38940 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  t transaction to
38950 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68   commit.** if th
38960 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72  ere are no other
38970 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69   BLOBs, no pendi
38980 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ng prepared stat
38990 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a  ements, and the.
389a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
389b0 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74  ection is in aut