/ Hex Artifact Content
Login

Artifact 4fcaad008e3b468d7202e749d5a8b81e59afcf5a:


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 30 39 20 32 30 30 38 2f  in,v 1.309 2008/
05f0: 30 34 2f 32 37 20 32 32 3a 32 39 3a 30 32 20 64  04/27 22:29:02 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 0a 2a 2a 0a 2a 2a 20 45 61  ection}.**.** Ea
16d0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
16e0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
16f0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
1700: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
1710: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
1720: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
1730: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
1740: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1750: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1760: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1770: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1780: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1790: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
17a0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
17b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
17d0: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
17e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
17f0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
1800: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
1810: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
1820: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1830: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
1840: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1850: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1860: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1870: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1880: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1890: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
18a0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
18b0: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
18c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
18d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
18e0: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
18f0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1900: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1910: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1920: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1930: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1940: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1950: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1960: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1970: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
1980: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
1990: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19a0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19b0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19c0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
19e0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
19f0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a00: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a10: 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69  type.** definiti
1a20: 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ons.  The sqlite
1a30: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1a40: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1a50: 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20  re.** supported 
1a60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1a70: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1a80: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1a90: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  TS:.**.** {F1020
1aa0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ab0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ac0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20  e3_int64] types 
1ad0: 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20  specify a.**    
1ae0: 20 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67        64-bit sig
1af0: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1b00: 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20  ** {F10202} The 
1b10: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1b20: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1b30: 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69  t64] types speci
1b40: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1b50: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1b60: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1b70: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1b80: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1ba0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1bb0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1bc0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1bd0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1be0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1bf0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1c00: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1c10: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
1c20: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
1c30: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1c40: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
1c50: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1c60: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
1c70: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1c80: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1c90: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
1ca0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1cb0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
1cc0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
1cd0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
1ce0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
1cf0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
1d00: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
1d10: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
1d20: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
1d30: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
1d40: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1d50: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
1d60: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
1d70: 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23  ating-point.*/.#
1d80: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1d90: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1da0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1db0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1dc0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1dd0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1de0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1df0: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e00: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e10: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e20: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e30: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a  te3] object.  .*
1e40: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e50: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
1e60: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
1e70: 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70  alize] all.** [p
1e80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e90: 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ts] and.** [sqli
1ea0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
1eb0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c   close] all [sql
1ec0: 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42  ite3_blob | BLOB
1ed0: 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  s] .** associate
1ee0: 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
1ef0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
1f00: 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69  r.** to attempti
1f10: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
1f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f30: 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68  ..**.** <todo>Wh
1f40: 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65  at happens to pe
1f50: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
1f60: 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a  ns?  Are they.**
1f70: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72   rolled back, or
1f80: 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64   abandoned?</tod
1f90: 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
1fa0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  NTS:.**.** {F120
1fb0: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fc0: 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66  _close()] interf
1fd0: 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20  ace destroys an 
1fe0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1ff0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
2000: 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f  ocated by a prio
2010: 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
2020: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20  e3_open()],.**  
2030: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2040: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
2050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2060: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  )]..**.** {F1201
2070: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2080: 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f  close()] functio
2090: 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d  n releases all m
20a0: 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68  emory used by th
20b0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
20c0: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f  nnection and clo
20d0: 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c  ses all open fil
20e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  es..**.** {F1201
20f0: 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  3} If the databa
2100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f  se connection co
2110: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
2120: 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2130: 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61  tements] that ha
2140: 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20  ve not been.**  
2150: 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65          finalize
2160: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2170: 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20  nalize()], then 
2180: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2190: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
21a0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
21b0: 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74  SY] and leaves t
21c0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
21d0: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
21e0: 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65  4} Giving sqlite
21f0: 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c  3_close() a NULL
2200: 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2210: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2220: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2230: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2240: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2250: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2260: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2270: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
2280: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2290: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
22a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
22b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
22c0: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
22d0: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
22e0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
22f0: 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74  016} The paramet
2300: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2310: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
2320: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
2330: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
2340: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2350: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2360: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2370: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
2380: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2390: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
23a0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
23b0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
23c0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
23d0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
23e0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
23f0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
2400: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
2410: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
2420: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
2430: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2450: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2460: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2470: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
2480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2490: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
24a0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
24b0: 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65  f running.** one
24c0: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
24d0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
24e0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
24f0: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61    The.** SQL sta
2500: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2510: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2520: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2530: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
2540: 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  ().  The stateme
2550: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2560: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20  d one by one.** 
2570: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2580: 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
2590: 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74  rrupt is encount
25a0: 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c  ered or.** until
25b0: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
25c0: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
25d0: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74  ameter is an opt
25e0: 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63  ional.** callbac
25f0: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
2600: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2610: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
2620: 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64   results.** prod
2630: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
2640: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2650: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2660: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2670: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
2680: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
2690: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
26a0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
26b0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
26c0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
26d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
26f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
2700: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2710: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2720: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
2730: 65 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20  es nothing that 
2740: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2750: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2760: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2770: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2780: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2790: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
27a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
27b0: 73 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69  s just a conveni
27c0: 65 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a  ent wrapper..**.
27d0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
27e0: 2a 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54  * .** {F12101} T
27f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
2800: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76  ()] interface ev
2810: 61 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20  aluates zero or 
2820: 6d 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20  more UTF-8.**   
2830: 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20         encoded, 
2840: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
2850: 74 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65  ted, SQL stateme
2860: 6e 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nts in the.**   
2870: 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
2880: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66  inated string of
2890: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
28a0: 65 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a  er within the.**
28b0: 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
28c0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
28d0: 33 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20  3] object given 
28e0: 69 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  in the 1st param
28f0: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
2900: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
2910: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
2920: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c  3_exec()] is SQL
2930: 49 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a  ITE_OK if all.**
2940: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
2950: 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63  atements run suc
2960: 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
2970: 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65   {F12105} The re
2980: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
29a0: 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f   .**          no
29c0: 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64  n-zero error cod
29d0: 65 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61  e if any SQL sta
29e0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a  tement fails..**
29f0: 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20  .** {F12107} If 
2a00: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2a10: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a20: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
2a30: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
2a40: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2a50: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20  results and the 
2a60: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
2a70: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a   not NULL, then.
2a80: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a90: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2aa0: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
2ab0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2ac0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ad0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2ae0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73   each row of res
2af0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ult..**.** {F121
2b00: 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62  10} If the callb
2b10: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
2b20: 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65  n-zero value the
2b30: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
2b40: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
2b50: 69 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 20  ill aborted the 
2b60: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74  SQL statement it
2b70: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76   is currently ev
2b80: 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20  aluating,.**    
2b90: 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73        skip all s
2ba0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
2bb0: 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65  atements, and re
2bc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f  turn [SQLITE_ABO
2bd0: 52 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  RT]..**         
2be0: 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70   <todo>What happ
2bf0: 65 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 68  ens to *errmsg h
2c00: 65 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 72  ere?  Does the r
2c10: 65 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a 2a  esult code for.*
2c20: 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
2c30: 65 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 74  e3_errcode() get
2c40: 20 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a   set?</todo>.**.
2c50: 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20  ** {F12113} The 
2c60: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2c70: 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 61   routine will pa
2c80: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
2c90: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
2ca0: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
2cb0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
2cc0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2cd0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68  *.** {F12116} Th
2ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2cf0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
2d00: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2d10: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
2d20: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
2d30: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
2d40: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2d50: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
2d60: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
2d70: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2d80: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2d90: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2da0: 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72  sets the 3rd par
2db0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a  ameter of its .*
2dc0: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
2dd0: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
2de0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2df0: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
2e00: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
2e10: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
2e20: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2e30: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
2e40: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
2e50: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
2e60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
2e70: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
2e80: 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20  ** {F12122} The 
2e90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2ea0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
2eb0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2ec0: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
2ed0: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2ee0: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
2ef0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2f00: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
2f10: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
2f20: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
2f30: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
2f40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2f50: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
2f60: 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68  * {F12125} If th
2f70: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2f80: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
2f90: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
2fa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2fb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65  lite3_exec()] ne
2fc0: 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61  ver invokes a ca
2fd0: 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65  llback.  All que
2fe0: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
2ff0: 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e  esults are silen
3000: 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  tly discarded..*
3010: 2a 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 66  *.** {F12128} If
3020: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3030: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
3040: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79  r evaluating any
3050: 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20   of the SQL.**  
3060: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
3070: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
3080: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 68  lite3_exec()] th
3090: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
30a0: 28 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 20  ()] will.**     
30b0: 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 5b       return an [
30c0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
30d0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
30e0: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  K]..**.** {F1213
30f0: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3100: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
3110: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3120: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3130: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
3140: 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ded to [sqlite3_
3150: 65 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 74  exec()] and if t
3160: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3170: 20 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 20   (errmsg).**    
3180: 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
3190: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f 74  3_exec()] is not
31a0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 65   NULL, then an e
31b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 0a  rror message is.
31c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
31d0: 63 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  cated using the 
31e0: 65 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b 73  equivalent of [s
31f0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
3200: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
3210: 20 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64    *errmsg is mad
3220: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
3230: 61 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  at message..**.*
3240: 2a 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b  * {F12134} The [
3250: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3260: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
3270: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
3280: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
3290: 20 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 6d   *errmsg if errm
32a0: 73 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66  sg is NULL or if
32b0: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72   there are no er
32c0: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rors..**.** {F12
32d0: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  137} The [sqlite
32e0: 33 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 69  3_exec()] functi
32f0: 6f 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 6f  on sets the erro
3300: 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
3310: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ge.**          a
3320: 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
3330: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3340: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
3350: 73 67 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  sg()], and.**   
3360: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3370: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
3380: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
3390: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54  **.** {U12141} T
33a0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
33b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
33c0: 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61  xec()] must be a
33d0: 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  n valid and open
33e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
33f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3400: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  n]..**.** {U1214
3410: 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20  2} The database 
3420: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
3430: 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68  not be closed wh
3440: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3460: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3470: 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65  .** {U12143} The
3480: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3490: 6e 20 69 73 20 73 68 6f 75 6c 64 20 75 73 65 20  n is should use 
34a0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34b0: 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20   to free.**     
34c0: 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20       the memory 
34d0: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
34e0: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
34f0: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
3500: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73  **          mess
3510: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
3520: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   needed..**.** {
3530: 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20  U12145} The SQL 
3540: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
3550: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3560: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3570: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3580: 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20      must remain 
3590: 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20  unchanged while 
35a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
35b0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
35d0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
35e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3600: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3610: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3620: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3640: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3650: 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e  evaluted */.  in
3660: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3670: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3680: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3690: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
36a0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
36b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36d0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
36e0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
36f0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3720: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3730: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3740: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3750: 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d  t Codes {F10210}
3760: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3770: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3780: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3790: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
37a0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
37b0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
37c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
37d0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
37e0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
37f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3800: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3810: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3820: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
3830: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
3840: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f  result codes].*/
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3860: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3870: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3880: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3890: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
38a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
38b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
38c0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
38d0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
38e0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
38f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3900: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
3910: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
3920: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
3930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3940: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
3950: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
3960: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3980: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3990: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
39a0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
39b0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
39c0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
39d0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
39e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
39f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
3a10: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
3a20: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
3a30: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
3a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3a50: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
3a60: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
3a70: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
3a80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
3a90: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
3aa0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
3ab0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
3ac0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3ad0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
3ae0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
3af0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
3b00: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
3b10: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
3b20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
3b30: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
3b40: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
3b50: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
3b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b70: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
3b80: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
3b90: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
3ba0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
3bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
3bc0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
3bd0: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
3be0: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
3bf0: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
3c00: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
3c10: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
3c20: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
3c30: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
3c40: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
3c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
3c60: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
3c70: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
3c80: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
3ca0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
3cb0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
3cc0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
3cd0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
3ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
3cf0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
3d00: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
3d10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d20: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
3d30: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
3d40: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
3d50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d60: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
3d70: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
3d80: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
3d90: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
3da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
3db0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
3dc0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
3dd0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
3de0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
3df0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
3e00: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
3e10: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
3e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
3e30: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
3e40: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
3e50: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
3e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
3e70: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
3e80: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
3e90: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
3ea0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
3eb0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
3ec0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
3ed0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
3ee0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3ef0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
3f00: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
3f10: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
3f20: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
3f30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
3f40: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
3f50: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3f60: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
3f70: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
3f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
3f90: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
3fa0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
3fb0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
3fc0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3fd0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
3fe0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
3ff0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4000: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4010: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4020: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4030: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4040: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4050: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4060: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4070: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4080: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4090: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
40a0: 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b 45  s {F10220}.** KE
40b0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
40c0: 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65  d error code} {e
40d0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
40e0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
40f0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4100: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4110: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4120: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4130: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4140: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4150: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4160: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4170: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4180: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4190: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
41a0: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
41b0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
41c0: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
41d0: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
41e0: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
41f0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4200: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4210: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4220: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4230: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4240: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4250: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4260: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4270: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4280: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4290: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
42a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
42b0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
42c0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
42d0: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
42e0: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
42f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4300: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4310: 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 65  isabled.** for e
4320: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
4330: 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  nection using th
4340: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
4350: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4360: 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a  ()].** API..** .
4370: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
4380: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
4390: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
43a0: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
43b0: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
43c0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
43d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43e0: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
43f0: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
4400: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4410: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
4420: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
4430: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
4440: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
4450: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
4460: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
4470: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
4480: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
4490: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
44a0: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
44b0: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
44c0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
44d0: 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
44e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33  S:.**.** {F10223
44f0: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
4500: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
4510: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4520: 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a  always contains.
4530: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
4540: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65  lated primary re
4550: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70  sult code as a p
4560: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  refix..**.** {F1
4570: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65  0224} Primary re
4580: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
4590: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
45a0: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a   "_" character..
45b0: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45  **.** {F10225} E
45c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
45d0: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
45e0: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
45f0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
4600: 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65  .** {F10226} The
4610: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4620: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
4630: 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69  sult code contai
4640: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
4650: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
4660: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
4670: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
4680: 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20  sult code in.** 
4690: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
46a0: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
46b0: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
46c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
46d0: 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53 51  EAD          (SQ
46e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
46f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4700: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4710: 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45 5f  READ    (SQLITE_
4720: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4740: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4750: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4760: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4780: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
47a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
47b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
47c0: 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54 45  SYNC     (SQLITE
47d0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47f0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4810: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4830: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 28  _FSTAT         (
4840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4850: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
4860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
4870: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
4880: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
4890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
48a0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
48b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
48c0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
48e0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
48f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4900: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4920: 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51 4c  OCKED       (SQL
4930: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
4940: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4950: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
4960: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4970: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
4980: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4990: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
49a0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
49b0: 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10230}.**.** 
49c0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
49d0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
49e0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
49f0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
4a00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
4a10: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4a20: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
4a30: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
4a40: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
4a50: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
4a60: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
4a70: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
4a80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
4a90: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
4aa0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4ab0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
4ac0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
4ad0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4ae0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
4af0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
4b00: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
4b10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
4b20: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
4b30: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4b40: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
4b50: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
4b60: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4b70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
4b80: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4b90: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
4ba0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
4bb0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4bc0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
4bd0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
4be0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
4bf0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
4c00: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
4c10: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4c20: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
4c30: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
4c40: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4c50: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
4c60: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
4c70: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
4c80: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
4c90: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
4ca0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
4cb0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
4cc0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
4cd0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 46  aracteristics {F
4ce0: 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10240}.**.** The
4cf0: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
4d00: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
4d10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
4d20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
4d30: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
4d40: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
4d50: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
4d60: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
4d70: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
4d80: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
4d90: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
4da0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
4db0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
4dc0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
4dd0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4de0: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
4df0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
4e00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
4e10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
4e20: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
4e30: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
4e40: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
4e60: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
4e70: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
4e80: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
4e90: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
4ea0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
4eb0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
4ec0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
4ed0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
4ee0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
4ef0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
4f00: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
4f10: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
4f20: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
4f30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
4f40: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
4f50: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
4f60: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
4f70: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
4f80: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
4f90: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
4fa0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
4fb0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4fc0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
4fd0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
4fe0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
4ff0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
5000: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
5010: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
5020: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5050: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5070: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5080: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50a0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
50b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
50c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50d0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
50e0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5110: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5120: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5130: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
5140: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5170: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5190: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
51a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
51b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51c0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
51d0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5200: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5230: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
5240: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5250: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
5260: 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a  els {F10250}.**.
5270: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5280: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5290: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
52a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
52b0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
52c0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
52d0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
52e0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
52f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5310: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5320: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5330: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5340: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5350: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5370: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
53a0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
53b0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
53c0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
53d0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
53e0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
53f0: 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a  lags {F10260}.**
5400: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5410: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5420: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5430: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5440: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5450: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5460: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5470: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5480: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5490: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
54a0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
54b0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
54c0: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
54d0: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
54e0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
54f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5500: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5510: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5520: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5530: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5540: 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53  ed. The SQLITE_S
5550: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20  YNC_NORMAL flag 
5560: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65  means .** to use
5570: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
5580: 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53  semantics. The S
5590: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
55a0: 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74  flag means .** t
55b0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73  o use Mac OS-X s
55c0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
55d0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
55e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
55f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
5600: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5620: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
5630: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
5640: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
5650: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
5660: 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  10.../*.** CAPI3
5670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5680: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5690: 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a  le {F11110}.**.*
56a0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
56b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
56c0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
56d0: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
56e0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
56f0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
5700: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
5710: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5720: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5730: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5740: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5750: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5760: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5770: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5780: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5790: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
57a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57b0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
57c0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
57d0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
57e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
57f0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
5800: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5810: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5820: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5830: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5840: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5850: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5860: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5870: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5880: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5890: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
58a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
58b0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
58c0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
58d0: 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76  F11120}.**.** Ev
58e0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
58f0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5900: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5910: 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69  d contains a poi
5920: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e  nter to.** an in
5930: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
5940: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5950: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5960: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5970: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5980: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5990: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
59a0: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
59b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
59c0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
59d0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
59e0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
59f0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
5a00: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
5a10: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
5a20: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20  mal fsync()..*  
5a30: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
5a40: 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20  e is an.** OS-X 
5a50: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
5a60: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
5a70: 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62  _DATA flag may b
5a80: 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20  e ORed in to.** 
5a90: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
5aa0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
5ab0: 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20  he file and not 
5ac0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
5ad0: 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e  to be.** synced.
5ae0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65  .** .** The inte
5af0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
5b00: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5b10: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
5b20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
5b30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5b50: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5b60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
5b80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b90: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5ba0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5bc0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
5bd0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
5be0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
5bf0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
5c00: 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54  the lock.  .** T
5c10: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5c20: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c  dLock() method l
5c30: 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ooks.** to see i
5c40: 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  f any database c
5c50: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65  onnection, eithe
5c60: 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f  r in this.** pro
5c70: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
5c80: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
5c90: 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53  s holding an RES
5ca0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5cb0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5cc0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5cd0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5ce0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5cf0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5d00: 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a  false if not..**
5d10: 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f   .** The xFileCo
5d20: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
5d30: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
5d40: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
5d50: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
5d60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5d70: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
5d80: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
5d90: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
5da0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
5db0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
5dc0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
5dd0: 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  p" argument.** i
5de0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63  s an integer opc
5df0: 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72 64  ode.   The third
5e00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
5e10: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
5e20: 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e  r which is inten
5e30: 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e  ded to be a poin
5e40: 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75  ter.** to a stru
5e50: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
5e60: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
5e70: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
5e80: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
5e90: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
5ea0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
5eb0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
5ec0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
5ed0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
5ee0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
5ef0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
5f00: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
5f10: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
5f20: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
5f30: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
5f40: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
5f50: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
5f60: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
5f70: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
5f80: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
5f90: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
5fa0: 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65  erves opcodes le
5fb0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
5fc0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a  its own use. .**
5fd0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
5fe0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
5ff0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6000: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6010: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6020: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6030: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6040: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6050: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6060: 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65  codes .** greate
6070: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6080: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6090: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
60a0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
60b0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
60c0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
60d0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
60e0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
60f0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
6100: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
6110: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6120: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6130: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6140: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6150: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6160: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6170: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6180: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6190: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
61a0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
61b0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
61c0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
61d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
61e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
61f0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
6200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6210: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6230: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
6240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6250: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6270: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6280: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6290: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
62a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
62b0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
62c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
62d0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
62e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
62f0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
6300: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6310: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6320: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6330: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6340: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6350: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6360: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6370: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6380: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6390: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
63a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
63b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6400: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6410: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6420: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6430: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6440: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6450: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6460: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6470: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6480: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6490: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
64a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
64b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6500: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6510: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6520: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6530: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6540: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6550: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6560: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6570: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6580: 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  e()..*/.typedef 
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
65a0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
65b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
65c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65d0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
65e0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
65f0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
6600: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6610: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6620: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6630: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6640: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6650: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6660: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6670: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6680: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6690: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
66a0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
66b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
66c0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
66d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
66e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
66f0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
6700: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
6710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6720: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6730: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6740: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6750: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6760: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6770: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6780: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6790: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
67a0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
67b0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
67c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
67d0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
67e0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
67f0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
6800: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6810: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6820: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6830: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6840: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6850: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6860: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6870: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6880: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
6890: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
68a0: 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a  pcodes {F11310}.
68b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
68c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
68d0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
68e0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
68f0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
6900: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6910: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
6920: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6930: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
6940: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
6950: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
6960: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
6970: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
6980: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
6990: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
69a0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
69b0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
69c0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
69d0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
69e0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
69f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6a00: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
6a10: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
6a20: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6a30: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
6a40: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
6a50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6a60: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
6a70: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
6a80: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
6a90: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
6aa0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
6ab0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
6ac0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
6ad0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
6ae0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
6af0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
6b00: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
6b10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
6b20: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
6b30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6b40: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b  : Mutex Handle {
6b50: 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17110}.**.** Th
6b60: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
6b70: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
6b80: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
6b90: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
6ba0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
6bb0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
6bc0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
6bd0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
6be0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
6bf0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
6c00: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
6c10: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
6c20: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
6c30: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
6c40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6c50: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
6c60: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
6c70: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
6c80: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
6c90: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6ca0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
6cb0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
6cc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6cd0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
6ce0: 6a 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a  ject {F11140}.**
6cf0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
6d00: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
6d10: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
6d20: 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  face between the
6d30: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20  .** SQLite core 
6d40: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
6d50: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
6d60: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
6d70: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
6d80: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
6d90: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
6da0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
6db0: 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f  *.** The iVersio
6dc0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
6dd0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
6de0: 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74  e larger for fut
6df0: 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
6e00: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
6e10: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
6e20: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
6e30: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
6e40: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
6e50: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
6e60: 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
6e70: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
6e80: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
6e90: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
6ea0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
6eb0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
6ec0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
6ed0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
6ee0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
6ef0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
6f00: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
6f10: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
6f20: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
6f30: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
6f40: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
6f50: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
6f60: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
6f70: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
6f80: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
6f90: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
6fa0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
6fb0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
6fc0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
6fd0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
6fe0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
6ff0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7000: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
7010: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
7020: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
7030: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
7040: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
7050: 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72  vfs .** structur
7060: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7070: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7080: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7090: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
70a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
70b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
70c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
70d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
70e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
70f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7100: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
7110: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7120: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
7130: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7140: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7150: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7160: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7170: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7180: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7190: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
71a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
71b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
71c0: 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74  * {F11141} SQLit
71d0: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
71e0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
71f0: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
7200: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
7210: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
7220: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
7230: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
7240: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
7250: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
7260: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
7270: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
7280: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
7290: 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65  d.  {END} So the
72a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
72b0: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
72c0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
72d0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
72e0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
72f0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
7300: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
7310: 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20  ** {F11142} The 
7320: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7330: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
7340: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
7350: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
7360: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7370: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
7380: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
7390: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
73a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
73b0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
73c0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
73d0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
73e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
73f0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
7400: 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d  N_CREATE]. {END}
7410: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
7420: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
7430: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
7440: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
7450: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
7460: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7470: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7480: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7490: 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20  y be.** set..** 
74a0: 0a 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c  .** {F11143} SQL
74b0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
74c0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
74d0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
74e0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
74f0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
7500: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
7510: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a  ng opened:.** .*
7520: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
7530: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
7540: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
7550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
7560: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
7570: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7580: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
7590: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
75a0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
75b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
75c0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
75d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
75e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
75f0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7600: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
7610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
7620: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
7630: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7640: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7650: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7660: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7670: 61 6e 67 65 73 20 74 68 65 20 77 61 79 20 69 74  anges the way it
7680: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
7690: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
76a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
76b0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
76c0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
76d0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
76e0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
76f0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
7700: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
7710: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
7720: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
7730: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
7740: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
7750: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
7760: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
7770: 75 6c 64 20 72 65 74 75 72 6e 20 0a 2a 2a 20 53  uld return .** S
7780: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
7790: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
77a0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
77b0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
77c0: 61 73 65 20 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  ase .** file wil
77d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
77e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
77f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
7800: 69 6e 20 61 20 72 61 6e 64 6f 6d 20 0a 2a 2a 20  in a random .** 
7810: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
7820: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
7830: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
7840: 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  ** .** SQLite mi
7850: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
7860: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
7870: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
7880: 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a  Open.** method:.
7890: 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ** .** <ul>.** <
78a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
78b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
78c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
78d0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
78e0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
78f0: 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {F11145} The [SQ
7900: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7910: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
7920: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7930: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
7940: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
7950: 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20 54  sed.  {F11146} T
7960: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
7970: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7980: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
7990: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
79a0: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
79b0: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
79c0: 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68   .** {F11147} Th
79d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
79e0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
79f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7a00: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
7a10: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
7a20: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
7a30: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
7a40: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
7a50: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
7a60: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45  atabase file. {E
7a70: 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  ND}.** .** {F111
7a80: 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f  48} At least szO
7a90: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
7aa0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
7ab0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a 2a  ted by SQLite .*
7ac0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
7ad0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
7ae0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
7af0: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
7b00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
7b10: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
7b20: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
7b30: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
7b40: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
7b50: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
7b60: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
7b70: 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  n..** .** {F1114
7b80: 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  9} The flags arg
7b90: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
7ba0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
7bb0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
7bc0: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
7bd0: 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20 6f   the existance o
7be0: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
7bf0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
7c00: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
7c10: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
7c20: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
7c30: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
7c40: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
7c50: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
7c60: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
7c70: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
7c80: 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44 7d  readable.  {END}
7c90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
7ca0: 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79   a .** directory
7cb0: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35 30  ..** .** {F11150
7cc0: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
7cd0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
7ce0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
7cf0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 0a 2a 2a  e+1 bytes for.**
7d00: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
7d10: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
7d20: 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  name and xFullPa
7d30: 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d  thname. {F11151}
7d40: 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73 69   The exact.** si
7d50: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
7d60: 20 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f 20   buffer is also 
7d70: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
7d80: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a 2a  meter to both .*
7d90: 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d  * methods. {END}
7da0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
7db0: 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61 72  uffer is not lar
7dc0: 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49 54  ge enough, SQLIT
7dd0: 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68  E_CANTOPEN.** sh
7de0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
7df0: 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61 6e  . As this is han
7e00: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
7e10: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
7e20: 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  .** vfs implemen
7e30: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
7e40: 6e 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76 65  ndeavor to preve
7e50: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
7e60: 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61 6d  ng .** mxPathnam
7e70: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
7e80: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
7e90: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e  .** .** The xRan
7ea0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
7eb0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
7ec0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
7ed0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
7ee0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
7ef0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
7f00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
7f10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
7f20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
7f30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
7f40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
7f50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
7f60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
7f70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
7f80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
7f90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
7fa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
7fb0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
7fc0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
7fd0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
7fe0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
7ff0: 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65  d.  The.** xSlee
8000: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
8010: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
8020: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
8030: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
8040: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
8050: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
8060: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
8070: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
8080: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
8090: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
80a0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
80b0: 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74  nd.** time..*/.t
80c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
80d0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
80e0: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
80f0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
8100: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
8110: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
8120: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
8130: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
8140: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
8150: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
8160: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
8170: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
8180: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
8190: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
81a0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
81b0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
81c0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
81d0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
81e0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
81f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
8200: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
8210: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
8220: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
8230: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
8240: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
8250: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
8260: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
8270: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
8280: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8290: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
82a0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
82b0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
82c0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
82d0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
82e0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
82f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8300: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8310: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
8320: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
8330: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8340: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8350: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8360: 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28  (*xGetTempname)(
8370: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8380: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
8390: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
83a0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
83b0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
83c0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
83d0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
83e0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
83f0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
8400: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8410: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
8420: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
8430: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8440: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
8450: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
8460: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
8470: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
8480: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
8490: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
84a0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
84b0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
84c0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
84d0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
84e0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
84f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
8500: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
8510: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
8520: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
8530: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
8540: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
8550: 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  uble*);.  /* New
8560: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
8570: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
8580: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
8590: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
85a0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
85b0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
85c0: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
85d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
85e0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
85f0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
8600: 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a  od {F11190}.**.*
8610: 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65  * {F11191} These
8620: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8630: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
8640: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
8650: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
8660: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
8670: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
8680: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d  s] object. {END}
8690: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
86a0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
86b0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
86c0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
86d0: 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f  is.** looking fo
86e0: 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74  r.  {F11192} Wit
86f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8700: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
8710: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8720: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8730: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8740: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8750: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8760: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8770: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8780: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8790: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
87a0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
87b0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
87c0: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
87d0: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
87e0: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
87f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
8800: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
8810: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8820: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8830: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8840: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8850: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8860: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8870: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8880: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8890: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
88a0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
88b0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
88c0: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
88d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
88e0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
88f0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
8900: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
8910: 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  es the.** [SQLIT
8920: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
8930: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
8940: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
8950: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20   SQLite..** The 
8960: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8970: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
8980: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
8990: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
89a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
89b0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
89c0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20  .**.** {F12201} 
89d0: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
89e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
89f0: 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  as the .**      
8a00: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65      [extended re
8a10: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
8a20: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
8a30: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
8a40: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
8a50: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
8a60: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
8a70: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
8a80: 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61 62  erface will enab
8a90: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8aa0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8ab0: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8ac0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8ae0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8af0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8b00: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8b10: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8b20: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8b30: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8b40: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8b50: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8b60: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8b70: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8b80: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8b90: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8ba0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8bb0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8bc0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8bd0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8be0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8bf0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8c00: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8c10: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8c20: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8c30: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8c40: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8c50: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8c60: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8c70: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8c80: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8c90: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8ca0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8cb0: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8cc0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8cd0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8ce0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
8cf0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
8d00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
8d10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
8d20: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
8d30: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
8d40: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
8d50: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
8d60: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
8d70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
8d80: 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66  * shown in the f
8d90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
8da0: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
8db0: 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65   inserts.** have
8dc0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
8dd0: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  n this database 
8de0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
8df0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
8e00: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
8e10: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
8e20: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
8e30: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a  he rowid of the.
8e40: 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ** inserted row 
8e50: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
8e60: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
8e70: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
8e80: 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  er.** is running
8e90: 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  .  But once the 
8ea0: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
8eb0: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
8ec0: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  turned.** by thi
8ed0: 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
8ee0: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
8ef0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
8f00: 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67  ore the.** trigg
8f10: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
8f20: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
8f30: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
8f40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
8f50: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
8f60: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
8f70: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
8f80: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
8f90: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
8fa0: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
8fb0: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
8fc0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
8fd0: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
8fe0: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
8ff0: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
9000: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
9010: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
9020: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
9030: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
9040: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
9050: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
9060: 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e  R REPLACE .** en
9070: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
9080: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
9090: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
90a0: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
90b0: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
90c0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
90d0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
90e0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
90f0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
9100: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
9110: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
9120: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
9130: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
9140: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
9150: 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  e. .**.** For th
9160: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
9170: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69  is routine, an i
9180: 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65  nsert is conside
9190: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
91a0: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
91b0: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
91c0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
91d0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
91e0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d  :.**.** {F12221}
91f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
9200: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
9210: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
9220: 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
9230: 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65      rowid of the
9240: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
9250: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64  cessful insert d
9260: 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  one.**          
9270: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
9280: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9290: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
92a0: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
92b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
92c0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
92d0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
92e0: 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69     been no quali
92f0: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 20 6f 6e  fying inserts on
9300: 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 69 6f 6e   that connection
9310: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d  ..**.** {F12223}
9320: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
9330: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
9340: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
9350: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
9360: 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20  same value when 
9370: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
9380: 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e  same trigger con
9390: 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
93a0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
93b0: 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20  ore and after a 
93c0: 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20  ROLLBACK..**.** 
93d0: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
93e0: 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20 61  ** {U12232} If a
93f0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
9400: 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65   does a new inse
9410: 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  rt on the same.*
9420: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
9430: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
9440: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
9450: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
9460: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
9470: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
9480: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
9490: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
94a0: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
94b0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
94c0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
94d0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
94e0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
94f0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
9500: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
9510: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
9520: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
9530: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
9540: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
9550: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
9560: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
9570: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
9580: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
9590: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
95a0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
95b0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
95c0: 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a  dified {F12240}.
95d0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
95e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
95f0: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
9600: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
9610: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
9620: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
9630: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
9640: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
9650: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
9660: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65  .** on the conne
9670: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
9680: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
9690: 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a  ameter.  Only.**
96a0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
96b0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
96c0: 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45  fied by the INSE
96d0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a  RT, UPDATE, or.*
96e0: 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
96f0: 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
9700: 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
9710: 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
9720: 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74  triggers are not
9730: 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68   counted. Use th
9740: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
9750: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
9760: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  tion.** to find 
9770: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
9780: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c   of changes incl
9790: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
97a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
97b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63  ..**.** A "row c
97c0: 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
97d0: 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
97e0: 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
97f0: 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
9800: 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
9810: 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
9820: 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
9830: 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
9840: 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
9850: 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63  cts of REPLACE c
9860: 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
9870: 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
9880: 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
9890: 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c  ing, DROP TABLE,
98a0: 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
98b0: 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
98c0: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
98d0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
98e0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  s..**.** A "trig
98f0: 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
9900: 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
9910: 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
9920: 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
9930: 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
9940: 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74  a trigger.  Most
9950: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
9960: 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
9970: 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
9980: 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
9990: 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
99a0: 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
99b0: 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
99c0: 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
99d0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
99e0: 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
99f0: 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
9a00: 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
9a10: 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
9a20: 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
9a30: 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
9a40: 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
9a50: 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
9a60: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71  *.** Calling [sq
9a70: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
9a80: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
9a90: 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
9aa0: 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
9ab0: 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
9ac0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ontext..**.** Th
9ad0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
9ae0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
9af0: 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
9b00: 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
9b10: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
9b20: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
9b30: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
9b40: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
9b50: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
9b60: 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e  t..**.** So when
9b70: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
9b80: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
9b90: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
9ba0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
9bb0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
9bc0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
9bd0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
9be0: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
9bf0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
9c00: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a   the top level..
9c10: 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  ** Within the bo
9c20: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
9c30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
9c40: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
9c50: 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  .** can be calle
9c60: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
9c70: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
9c80: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
9c90: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
9ca0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
9cb0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
9cc0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
9cd0: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
9ce0: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
9cf0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
9d00: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
9d10: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69  es not include i
9d20: 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  n changes.** cau
9d30: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
9d40: 72 73 20 73 69 6e 63 65 20 74 68 65 79 20 68 61  rs since they ha
9d50: 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
9d60: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  text..**.** SQLi
9d70: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
9d80: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
9d90: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
9da0: 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45  thout.** a WHERE
9db0: 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70   clause by dropp
9dc0: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
9dd0: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
9de0: 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20  This is much.** 
9df0: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
9e00: 67 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  g through and de
9e10: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
9e20: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
9e30: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20  the.** table.)  
9e40: 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20  Because of this 
9e50: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
9e60: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a  e deletions in.*
9e70: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
9e80: 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
9e90: 77 20 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69  w changes and wi
9ea0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
9eb0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69  d.** by the sqli
9ec0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
9ed0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
9ee0: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
9ef0: 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20  ions..** To get 
9f00: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
9f10: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
9f20: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
9f30: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
9f40: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
9f50: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
9f60: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
9f70: 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68  *.** {F12241} Th
9f80: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
9f90: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  es()] function r
9fa0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
9fb0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
9fc0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
9fd0: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
9fe0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
9ff0: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
a000: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
a010: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
a020: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
a030: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
a040: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
a050: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
a060: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
a070: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
a080: 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
a090: 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e  en any qualifyin
a0a0: 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  g row changes..*
a0b0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
a0c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d  :.**.** {U12252}
a0d0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
a0e0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
a0f0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
a100: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a110: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
a120: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
a130: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
a140: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
a150: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
a160: 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72           is unpr
a170: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 75 6e  edictable and un
a180: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
a190: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
a1a0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
a1b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
a1c0: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
a1d0: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31  ows Modified {F1
a1e0: 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  2260}.***.** Thi
a1f0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
a200: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
a210: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
a220: 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54  sed.** by INSERT
a230: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
a240: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
a250: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
a260: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f   handle.** was o
a270: 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e  pened.  The coun
a280: 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  t includes all c
a290: 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20  hanges from all 
a2a0: 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65  trigger.** conte
a2b0: 78 74 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f  xts.  But the co
a2c0: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
a2d0: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
a2e0: 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  d to.** implemen
a2f0: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
a300: 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61  aints, do rollba
a310: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
a320: 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44  cessing,.** or D
a330: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
a340: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
a350: 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  nges.** are coun
a360: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
a370: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
a380: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
a390: 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77  completed .** (w
a3a0: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
a3b0: 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
a3c0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
a3d0: 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b  eset()] or .** [
a3e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
a3f0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ()])..**.** SQLi
a400: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
a410: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
a420: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
a430: 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45  thout.** a WHERE
a440: 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70   clause by dropp
a450: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
a460: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
a470: 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20  This is much.** 
a480: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
a490: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
a4a0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
a4b0: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
a4c0: 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  om the table.)  
a4d0: 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68  Because of.** th
a4e0: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
a4f0: 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e   the change coun
a500: 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52  t for "DELETE FR
a510: 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62  OM table" will b
a520: 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64  e.** zero regard
a530: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
a540: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
a550: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
a560: 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61  lly in the.** ta
a570: 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61  ble. To get an a
a580: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
a590: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
a5a0: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
a5b0: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
a5c0: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
a5d0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53  instead..**.** S
a5e0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
a5f0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
a600: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
a610: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20   INVARIANTS:.** 
a620: 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65  .** {F12261} The
a630: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
a640: 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72  changes()] retur
a650: 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
a660: 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
a670: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
a680: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
a690: 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20   UPDATE, and/or 
a6a0: 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20  DELETE.**       
a6b0: 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e     statements on
a6c0: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
a6d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
a6e0: 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20   in any.**      
a6f0: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
a700: 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64  ext, since the d
a710: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a720: 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  on was.**       
a730: 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a     created..**.*
a740: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
a750: 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66  *.** {U12264} If
a760: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
a770: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
a780: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
a790: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a7a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
a7b0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
a7c0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
a7d0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
a7e0: 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20   value .**      
a7f0: 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20      returned is 
a800: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
a810: 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  d unmeaningful..
a820: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
a830: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
a840: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
a850: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
a860: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
a870: 67 20 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d  g Query {F12270}
a880: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
a890: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
a8a0: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
a8b0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
a8c0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
a8d0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
a8e0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
a8f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
a900: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
a910: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
a920: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
a930: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
a940: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
a950: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
a960: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
a970: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
a980: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
a990: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
a9a0: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
a9b0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
a9c0: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
a9d0: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
a9e0: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
a9f0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
aa00: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
aa10: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
aa20: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
aa30: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
aa40: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
aa50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
aa60: 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20  tion that.** is 
aa70: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
aa80: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
aa90: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
aaa0: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
aab0: 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72  If an SQL is ver
aac0: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
aad0: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
aae0: 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  en sqlite3_inter
aaf0: 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c  rupt().** is cal
ab00: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
ab10: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
ab20: 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65  pportunity to be
ab30: 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a   interrupted..**
ab40: 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e   It might contin
ab50: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
ab60: 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72  ..** An SQL oper
ab70: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
ab80: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
ab90: 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
aba0: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66  _INTERRUPT].  If
abb0: 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
abc0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
abd0: 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20  s an.** INSERT, 
abe0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
abf0: 45 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  E that is inside
ac00: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
ac10: 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68  nsaction, .** th
ac20: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
ac30: 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62  ansaction will b
ac40: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
ac50: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20  tomatically..** 
ac60: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
ac70: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
ac80: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
ac90: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
aca0: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
acb0: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
acc0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
acd0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
ace0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
acf0: 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
ad00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
ad10: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
ad20: 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
ad30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
ad40: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
ad50: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
ad60: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ad70: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ad80: 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
ad90: 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
ada0: 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
adb0: 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20  onal row of.**  
adc0: 20 20 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a          data..**
add0: 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79  .** {F12272} Any
ade0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
adf0: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
ae00: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
ae10: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
ae20: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
ae30: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
ae40: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49  RRUPT]..**.** LI
ae50: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
ae60: 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74 68 65   {U12279} If the
ae70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ae80: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
ae90: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
aea0: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
aeb0: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
aec0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
aed0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
aee0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
aef0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
af00: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
af10: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
af20: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
af30: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
af40: 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a  te {F10510}.**.*
af50: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
af60: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
af70: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
af80: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
af90: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
afa0: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
afb0: 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
afc0: 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
afd0: 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
afe0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
aff0: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
b000: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
b010: 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
b020: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
b030: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
b040: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
b050: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
b060: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
b070: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
b080: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
b090: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
b0a0: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
b0b0: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
b0c0: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
b0d0: 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
b0e0: 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
b0f0: 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
b100: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
b110: 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
b120: 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
b130: 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
b140: 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
b150: 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
b160: 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
b170: 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
b180: 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
b190: 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
b1a0: 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
b1b0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
b1c0: 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
b1d0: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
b1e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
b1f0: 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
b200: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
b210: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
b220: 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20   and.** so will 
b230: 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
b240: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
b250: 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ct SQL..**.** IN
b260: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
b270: 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c  {F10511} The sql
b280: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20  ite3_complete() 
b290: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
b2a0: 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f  lete16() functio
b2b0: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ns.**          r
b2c0: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
b2d0: 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c  zero) if and onl
b2e0: 79 20 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a  y if the last.**
b2f0: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68            non-wh
b300: 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69  itespace token i
b310: 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
b320: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
b330: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  t.**          is
b340: 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20   not in between 
b350: 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
b360: 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
b370: 49 47 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  IGGER.**        
b380: 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a    statement..**.
b390: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
b3a0: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54  **.** {U10512} T
b3b0: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
b3c0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d  te3_complete() m
b3d0: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
b3e0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
b3f0: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
b400: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33  g..**.** {U10513
b410: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73  } The input to s
b420: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
b430: 36 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65  6() must be a ze
b440: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
b450: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36            UTF-16
b460: 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
b470: 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
b480: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
b490: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
b4a0: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
b4b0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
b4c0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
b4d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b4e0: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
b4f0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
b500: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
b510: 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a  rs {F12310}.**.*
b520: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
b530: 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c  dentifies a call
b540: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
b550: 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69  at might be.** i
b560: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
b570: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
b580: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
b590: 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20  abase table .** 
b5a0: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
b5b0: 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68  ead or process h
b5c0: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66  as locked..** If
b5d0: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
b5e0: 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
b5f0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
b600: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
b610: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
b620: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
b630: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
b640: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
b650: 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  k..** If the bus
b660: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  y callback is no
b670: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
b680: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  .** callback wil
b690: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
b6a0: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
b6b0: 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61    The.** first a
b6c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
b6d0: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
b6e0: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
b6f0: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
b700: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
b710: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75  ment to this rou
b720: 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  tine.  The secon
b730: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
b740: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
b750: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
b760: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
b770: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
b780: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
b790: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
b7a0: 76 65 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a  vent.   If the.*
b7b0: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
b7c0: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
b7d0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
b7e0: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
b7f0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
b800: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
b810: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
b820: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
b830: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
b840: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
b850: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
b860: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
b870: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
b880: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
b890: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
b8a0: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
b8b0: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
b8c0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
b8d0: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
b8e0: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
b8f0: 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20  arantee that.** 
b900: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
b910: 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ed when there is
b920: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
b930: 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  ..** If SQLite d
b940: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
b950: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
b960: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
b970: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
b980: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
b990: 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
b9a0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
b9b0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
b9c0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
b9d0: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
b9e0: 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ng the.** busy h
b9f0: 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
ba00: 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
ba10: 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
ba20: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
ba30: 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
ba40: 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
ba50: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
ba60: 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
ba70: 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
ba80: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
ba90: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
baa0: 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
bab0: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
bac0: 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
bad0: 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
bae0: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
baf0: 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
bb00: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
bb10: 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
bb20: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
bb30: 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
bb40: 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
bb50: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
bb60: 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
bb70: 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
bb80: 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
bb90: 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
bba0: 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
bbb0: 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
bbc0: 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
bbd0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
bbe0: 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
bbf0: 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
bc00: 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
bc10: 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
bc20: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
bc30: 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
bc40: 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
bc50: 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
bc60: 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
bc70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ed..**.** The de
bc80: 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
bc90: 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
bca0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  ** The [SQLITE_B
bcb0: 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
bcc0: 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
bcd0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
bce0: 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
bcf0: 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
bd00: 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
bd10: 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
bd20: 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
bd30: 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
bd40: 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
bd50: 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
bd60: 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
bd70: 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
bd80: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
bd90: 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
bda0: 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
bdb0: 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
bdc0: 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
bdd0: 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
bde0: 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
bdf0: 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
be00: 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
be10: 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
be20: 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
be30: 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65   If it is unable
be40: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
be50: 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
be60: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
be70: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
be80: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
be90: 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
bea0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
beb0: 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
bec0: 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
bed0: 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
bee0: 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
bef0: 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
bf00: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
bf10: 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20  D].  This error 
bf20: 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
bf30: 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
bf40: 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
bf50: 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
bf60: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
bf70: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
bf80: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
bf90: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
bfa0: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
bfb0: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
bfc0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
bfd0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
bfe0: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
bff0: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
c000: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
c010: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65  nt..**..** There
c020: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
c030: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
c040: 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
c050: 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
c060: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74  connection.  Set
c070: 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
c080: 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
c090: 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e  ny previous one.
c0a0: 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63   .** Note that c
c0b0: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
c0c0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
c0d0: 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
c0e0: 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75   clear.** the bu
c0f0: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
c100: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
c110: 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65  .** {F12311} The
c120: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
c130: 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69  andler()] functi
c140: 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
c150: 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
c160: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
c170: 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  k in the databas
c180: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
c190: 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31  ntified by the 1
c1a0: 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
c1b0: 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20  arameter with a 
c1c0: 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
c1d0: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
c1e0: 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a  he 2nd and 3rd.*
c1f0: 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
c200: 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eters..**.** {F1
c210: 32 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2312} The defaul
c220: 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  t busy handler f
c230: 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  or new database 
c240: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e  connections is N
c250: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ULL..**.** {F123
c260: 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
c270: 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  more database co
c280: 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61  nnection share a
c290: 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c 0a 2a   common cache,.*
c2a0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
c2b0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
c2c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
c2d0: 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
c2e0: 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
c2f0: 20 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73      the cache is
c300: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
c310: 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
c320: 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
c330: 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62   {F12316} If a b
c340: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
c350: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
c360: 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
c370: 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  te.**          i
c380: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 70 72  nterface that pr
c390: 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
c3a0: 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65  ng event will re
c3b0: 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
c3c0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
c3d0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53  **.** {F12318} S
c3e0: 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
c3f0: 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
c400: 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
c410: 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 20  ument which.**  
c420: 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
c430: 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
c440: 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
c450: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
c460: 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
c470: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
c480: 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
c490: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
c4a0: 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
c4b0: 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
c4c0: 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
c4d0: 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
c4e0: 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
c4f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
c500: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
c510: 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
c520: 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ler should not c
c530: 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61  all close the da
c540: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c550: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
c560: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
c570: 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ent that invoked
c580: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c590: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
c5a0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
c5b0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
c5c0: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
c5d0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
c5e0: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
c5f0: 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d  Timeout {F12340}
c600: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
c610: 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
c620: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c630: 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
c640: 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20  .** that sleeps 
c650: 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e  for a while when
c660: 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c   a.** table is l
c670: 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
c680: 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  ler will sleep m
c690: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
c6a0: 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74  til .** at least
c6b0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
c6c0: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68  ds of sleeping h
c6d0: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b  ave been done. {
c6e0: 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a  F12343} After.**
c6f0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
c700: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20  ds of sleeping, 
c710: 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
c720: 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63  rns 0 which.** c
c730: 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
c740: 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
c750: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
c760: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
c770: 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
c780: 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
c790: 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
c7a0: 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
c7b0: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
c7c0: 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
c7d0: 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
c7e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
c7f0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
c800: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
c810: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
c820: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
c830: 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74  ection.  If anot
c840: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
c850: 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a   was defined  .*
c860: 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  * (using [sqlite
c870: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
c880: 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
c890: 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
c8a0: 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
c8b0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
c8c0: 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  cleared..**.** I
c8d0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
c8e0: 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73   {F12341} The [s
c8f0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
c900: 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  out()] function 
c910: 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 70 72  overrides any pr
c920: 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
c930: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
c940: 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
c950: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c960: 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
c970: 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
c980: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
c990: 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
c9a0: 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68 65 20  {F12343} If the 
c9b0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
c9c0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
c9d0: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73  imeout()] is les
c9e0: 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  s than.**       
c9f0: 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a     or equal to z
ca00: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75  ero, then the bu
ca10: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
ca20: 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a  eared so that.**
ca30: 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75            all su
ca40: 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
ca50: 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
ca60: 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
ca70: 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
ca80: 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68 65 20  {F12344} If the 
ca90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
caa0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
cab0: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70  imeout()] is a p
cac0: 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
cad0: 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68      number N, th
cae0: 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  en a busy handle
caf0: 72 20 69 73 20 73 65 74 20 74 68 61 74 20 72 65  r is set that re
cb00: 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
cb10: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
cb20: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
cb30: 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65 72 66  n the VFS interf
cb40: 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  ace until either
cb50: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
cb60: 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
cb70: 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
cb80: 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20  tive sleep time 
cb90: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a  reported back.**
cba0: 20 20 20 20 20 20 20 20 20 20 62 79 20 78 53 6c            by xSl
cbb0: 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
cbc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
cbd0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
cbe0: 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
cbf0: 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
cc00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
cc10: 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
cc20: 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
cc30: 75 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a  ueries {F12370}.
cc40: 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
cc50: 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
cc60: 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
cc70: 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
cc80: 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
cc90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
cca0: 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
ccb0: 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
ccc0: 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
ccd0: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
cce0: 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
ccf0: 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
cd00: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
cd10: 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
cd20: 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
cd30: 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
cd40: 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
cd50: 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
cd60: 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
cd70: 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
cd80: 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
cd90: 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
cda0: 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
cdb0: 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
cdc0: 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
cdd0: 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
cde0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
cdf0: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
ce00: 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
ce10: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
ce20: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
ce30: 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20  UTF-8 strings.  
ce40: 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
ce50: 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
ce60: 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68  e array.  .** Th
ce70: 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
ce80: 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f  rs point to zero
ce90: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
cea0: 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e  ngs that .** con
ceb0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
cec0: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
ced0: 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
cee0: 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
cef0: 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
cf00: 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c  ts.  NULL.** val
cf10: 75 65 73 20 61 72 65 20 67 69 76 65 20 61 20 4e  ues are give a N
cf20: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c  ULL pointer.  Al
cf30: 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
cf40: 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55  re in.** their U
cf50: 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
cf60: 61 74 65 64 20 73 74 72 69 6e 67 20 72 65 70 72  ated string repr
cf70: 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
cf80: 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
cf90: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
cfa0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
cfb0: 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
cfc0: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65   consists of one
cfd0: 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
cfe0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
cff0: 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
d000: 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
d010: 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
d020: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
d030: 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
d040: 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
d050: 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
d060: 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
d070: 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
d080: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
d090: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
d0a0: 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
d0b0: 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
d0c0: 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
d0d0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
d0e0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
d0f0: 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
d100: 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
d110: 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
d120: 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
d130: 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
d140: 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
d150: 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
d160: 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
d170: 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
d180: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
d190: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
d1a0: 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
d1b0: 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
d1c0: 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
d1d0: 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
d1e0: 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
d1f0: 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
d200: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
d210: 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
d220: 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
d230: 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
d240: 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
d250: 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
d260: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
d270: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d280: 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
d290: 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
d2a0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
d2b0: 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
d2c0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
d2d0: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
d2e0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d2f0: 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
d300: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d310: 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
d320: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d330: 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
d340: 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
d350: 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
d360: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
d370: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d380: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
d390: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
d3a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
d3b0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
d3c0: 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
d3d0: 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
d3e0: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
d3f0: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
d400: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
d410: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
d420: 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
d430: 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
d440: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
d450: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
d460: 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
d470: 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
d480: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
d490: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
d4a0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
d4b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
d4c0: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
d4d0: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
d4e0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
d4f0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
d500: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
d510: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
d520: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
d530: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
d540: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65  s malloc-ed.  Be
d550: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
d560: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
d570: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
d580: 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
d590: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
d5a0: 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
d5b0: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
d5c0: 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
d5d0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
d5e0: 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a  rectly.  Only .*
d5f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
d600: 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
d610: 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
d620: 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
d630: 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
d640: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
d650: 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
d660: 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
d670: 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
d680: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
d690: 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
d6a0: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
d6b0: 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
d6c0: 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
d6d0: 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
d6e0: 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
d6f0: 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
d700: 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
d710: 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
d720: 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
d730: 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
d740: 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
d750: 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
d760: 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
d770: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
d780: 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
d790: 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
d7a0: 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
d7b0: 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
d7c0: 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
d7d0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
d7e0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
d7f0: 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
d800: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
d810: 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {F12371} If a [
d820: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
d830: 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
d840: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
d850: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
d860: 20 69 74 20 66 72 65 65 73 20 74 68 65 20 72 65   it frees the re
d870: 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72  sult table under
d880: 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61   construction, a
d890: 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  borts the.**    
d8a0: 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70        query in p
d8b0: 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e  rocess, skips an
d8c0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65  y subsequent que
d8d0: 72 69 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a  ries, sets the.*
d8e0: 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65 73 75  *          *resu
d8f0: 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74  ltp output point
d900: 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72  er to NULL and r
d910: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
d920: 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  OMEM]..**.** {F1
d930: 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f  2373} If the nco
d940: 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74  lumn parameter t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
d960: 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
d970: 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
d980: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65  then [sqlite3_ge
d990: 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65  t_table()] write
d9a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
d9b0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
d9c0: 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
d9d0: 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
d9e0: 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20  y into *ncolumn 
d9f0: 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a  if the query is.
da00: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63  **          succ
da10: 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66  essful (if the f
da20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
da30: 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a  SQLITE_OK)..**.*
da40: 2a 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68  * {F12374} If th
da50: 65 20 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72  e nrow parameter
da60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
da70: 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
da80: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
da90: 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
daa0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
dab0: 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
dac0: 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20   rows in the.** 
dad0: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
dae0: 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
daf0: 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74   into *nrow if t
db00: 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
db10: 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
db20: 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
db30: 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
db40: 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
db50: 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69  12376} The [sqli
db60: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
db70: 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69   function sets i
db80: 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75  ts *ncolumn valu
db90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  e.**          to
dba0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
dbb0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
dbc0: 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
dbd0: 71 75 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20  query in the.** 
dbe0: 20 20 20 20 20 20 20 20 20 73 71 6c 20 70 61 72           sql par
dbf0: 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65  ameter, or to ze
dc00: 72 6f 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ro if the query 
dc10: 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d  in sql has an em
dc20: 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pty.**          
dc30: 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
dc40: 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
dc50: 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a  able(.  sqlite3*
dc60: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ,             /*
dc70: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
dc80: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
dc90: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20  r *sql,      /* 
dca0: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
dcb0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
dcc0: 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f  *pResult,      /
dcd0: 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
dce0: 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
dcf0: 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20  *nrow,          
dd00: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
dd10: 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
dd20: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
dd30: 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20   *ncolumn,      
dd40: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
dd50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
dd60: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
dd70: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
dd80: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
dd90: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
dda0: 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
ddb0: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
ddc0: 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
ddd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dde0: 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
ddf0: 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
de00: 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a  ons {F17400}.**.
de10: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
de20: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
de30: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
de40: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
de50: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
de60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
de70: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
de80: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
de90: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
dea0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
deb0: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
dec0: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
ded0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
dee0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
def0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
df00: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
df10: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
df20: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
df30: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
df40: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
df50: 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73     Both routines
df60: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
df70: 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
df80: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
df90: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
dfa0: 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
dfb0: 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
dfc0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
dfd0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
dfe0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
dff0: 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
e000: 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
e010: 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
e020: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
e030: 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
e040: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
e050: 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
e060: 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
e070: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
e080: 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
e090: 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
e0a0: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
e0b0: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
e0c0: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
e0d0: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
e0e0: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
e0f0: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
e100: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
e110: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
e120: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
e130: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
e140: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
e150: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
e160: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
e170: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
e180: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
e190: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
e1a0: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
e1b0: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e1c0: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
e1d0: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
e1e0: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
e1f0: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
e200: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
e210: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
e220: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
e230: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
e240: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
e250: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
e260: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
e270: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
e280: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
e290: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
e2a0: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
e2b0: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
e2c0: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
e2d0: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
e2e0: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
e2f0: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
e300: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
e310: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
e320: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
e330: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
e340: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
e350: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
e360: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
e370: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
e380: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
e390: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
e3a0: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
e3b0: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
e3c0: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
e3d0: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
e3e0: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
e3f0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e400: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
e410: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
e420: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
e430: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
e440: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
e450: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
e460: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
e470: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
e480: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
e490: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
e4a0: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
e4b0: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
e4c0: 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
e4d0: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
e4e0: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
e4f0: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
e500: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
e510: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
e520: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
e530: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
e540: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
e550: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
e560: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
e570: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
e580: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
e590: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
e5a0: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
e5b0: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
e5c0: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
e5d0: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
e5e0: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
e5f0: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
e600: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
e610: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
e620: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
e630: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
e640: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
e650: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
e660: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
e670: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
e680: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
e690: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
e6a0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
e6b0: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
e6c0: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
e6d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
e6e0: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
e6f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e700: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
e710: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
e720: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
e730: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
e740: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
e750: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
e760: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
e770: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
e780: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
e790: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e7a0: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
e7b0: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
e7c0: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
e7d0: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
e7e0: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
e7f0: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
e800: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
e810: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
e820: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
e830: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
e840: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
e850: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
e860: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
e870: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
e880: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
e890: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
e8a0: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
e8b0: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
e8c0: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
e8d0: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
e8e0: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
e8f0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
e900: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
e910: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
e920: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
e930: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
e940: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
e950: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
e960: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
e970: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
e980: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
e990: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
e9a0: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
e9b0: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
e9c0: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
e9d0: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
e9e0: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
e9f0: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
ea00: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
ea10: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
ea20: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
ea30: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
ea40: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
ea50: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
ea60: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
ea70: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
ea80: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
ea90: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
eaa0: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
eab0: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
eac0: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
ead0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
eae0: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44   %Q option. {END
eaf0: 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  }  So, for examp
eb00: 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
eb10: 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
eb20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
eb30: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
eb40: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
eb50: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
eb60: 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
eb70: 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
eb80: 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
eb90: 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
eba0: 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
ebb0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
ebc0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
ebd0: 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
ebe0: 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
ebf0: 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
ec00: 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
ec10: 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
ec20: 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
ec30: 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
ec40: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
ec50: 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
ec60: 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
ec70: 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
ec80: 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
ec90: 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
eca0: 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
ecb0: 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
ecc0: 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
ecd0: 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
ece0: 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
ecf0: 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
ed00: 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
ed10: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
ed20: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20  **.** {F17403}  
ed30: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
ed40: 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
ed50: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
ed60: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20   interfaces.**  
ed70: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
ed80: 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20  either pointers 
ed90: 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
eda0: 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
edb0: 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20   held in.**     
edc0: 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74        memory obt
edd0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
ede0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
edf0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69   NULL pointers i
ee00: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
ee10: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
ee20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c  3_malloc()] fail
ee30: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36  s..**.** {F17406
ee40: 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
ee50: 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
ee60: 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a  rface writes a z
ee70: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
ee80: 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  *           UTF-
ee90: 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68  8 string into th
eea0: 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64  e buffer pointed
eeb0: 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
eec0: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  d parameter.**  
eed0: 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65           provide
eee0: 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74  d that the first
eef0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72   parameter is gr
ef00: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e  eater than zero.
ef10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20  .**.** {F17407} 
ef20: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
ef30: 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
ef40: 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69  ace does not wri
ef50: 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20  tes slots of.** 
ef60: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75            its ou
ef70: 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65  tput buffer (the
ef80: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
ef90: 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72  r) outside the r
efa0: 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
efb0: 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e    of 0 through N
efc0: 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74  -1 (where N is t
efd0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
efe0: 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er).**          
eff0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
f000: 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
f010: 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
f020: 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62       requested b
f030: 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
f040: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20  cification..**  
f050: 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74   .*/.char *sqlit
f060: 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
f070: 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
f080: 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
f090: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
f0a0: 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
f0b0: 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
f0c0: 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
f0d0: 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
f0e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f0f0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
f100: 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37  n Subsystem {F17
f110: 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  300}.**.** The S
f120: 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
f130: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
f140: 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
f150: 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
f160: 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
f170: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
f180: 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
f190: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
f1a0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
f1b0: 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
f1c0: 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
f1d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
f1e0: 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   The.** windows 
f1f0: 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
f200: 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72 65 65 20  malloc and free 
f210: 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
f220: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
f230: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f240: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f250: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
f260: 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
f270: 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
f280: 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
f290: 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
f2a0: 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
f2b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
f2c0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
f2d0: 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
f2e0: 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
f2f0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
f300: 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
f310: 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
f320: 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
f330: 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
f340: 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
f350: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
f360: 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
f370: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
f380: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
f390: 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
f3a0: 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
f3b0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
f3c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f3d0: 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
f3e0: 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
f3f0: 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
f400: 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
f410: 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
f420: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
f430: 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
f440: 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
f450: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
f460: 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
f470: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
f480: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
f490: 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
f4a0: 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
f4b0: 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
f4c0: 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
f4d0: 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
f4e0: 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
f4f0: 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
f500: 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
f510: 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
f520: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
f530: 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
f540: 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
f550: 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
f560: 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
f570: 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
f580: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
f590: 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
f5a0: 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
f5b0: 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
f5c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
f5d0: 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
f5e0: 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
f5f0: 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
f600: 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
f610: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f620: 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
f630: 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
f640: 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
f650: 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
f660: 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
f670: 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
f680: 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
f690: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
f6a0: 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
f6b0: 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
f6c0: 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
f6d0: 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
f6e0: 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
f6f0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
f700: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
f710: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
f720: 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
f730: 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
f740: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
f750: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
f760: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
f770: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
f780: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
f790: 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
f7a0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
f7b0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
f7c0: 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
f7d0: 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
f7e0: 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
f7f0: 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
f800: 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
f810: 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
f820: 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
f830: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f840: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
f850: 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65  loc()..** Sqlite
f860: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
f870: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
f880: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
f890: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
f8a0: 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
f8b0: 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
f8c0: 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
f8d0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f8e0: 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
f8f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
f900: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
f910: 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
f920: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
f930: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
f940: 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
f950: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
f960: 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
f970: 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
f980: 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
f990: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
f9a0: 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
f9b0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
f9c0: 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
f9d0: 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
f9e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
f9f0: 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
fa00: 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
fa10: 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
fa20: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
fa30: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
fa40: 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
fa50: 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
fa60: 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
fa70: 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
fa80: 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
fa90: 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
faa0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
fab0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
fac0: 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28  uses the malloc(
fad0: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  ), realloc().** 
fae0: 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69  and free() provi
faf0: 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64  ded by the stand
fb00: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b  ard C library. {
fb10: 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  F17382} However,
fb20: 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69   if .** SQLite i
fb30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fb40: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20  the following C 
fb50: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
fb60: 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  ro.**.** <blockq
fb70: 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d  uote> SQLITE_MEM
fb80: 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c  ORY_SIZE=<i>NNN<
fb90: 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  /i> </blockquote
fba0: 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69  >.**.** where <i
fbb0: 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69  >NNN</i> is an i
fbc0: 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c  nteger, then SQL
fbd0: 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
fbe0: 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20  tic.** array of 
fbf0: 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c  at least <i>NNN<
fc00: 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
fc10: 65 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 61  e and use that a
fc20: 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20  rray.** for all 
fc30: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
fc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fc50: 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41   needs. {END}  A
fc60: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d  dditional.** mem
fc70: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
fc80: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
fc90: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
fca0: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  eases..**.** In 
fcb0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
fcc0: 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
fcd0: 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
fce0: 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
fcf0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
fd00: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
fd10: 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
fd20: 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
fd30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fd40: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
fd50: 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
fd60: 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
fd70: 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
fd80: 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
fd90: 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
fda0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
fdb0: 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a   be.** used..**.
fdc0: 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f  ** The windows O
fdd0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
fde0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
fdf0: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
fe00: 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
fe10: 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
fe20: 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
fe30: 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
fe40: 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
fe50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
fe60: 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
fe70: 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
fe80: 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
fe90: 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a  cular windows.**
fea0: 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
feb0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
fec0: 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
fed0: 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
fee0: 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
fef0: 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
ff00: 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
ff10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
ff20: 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
ff30: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
ff40: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
ff50: 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65  ** {F17303}  The
ff60: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ff70: 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
ff80: 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
ff90: 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20  pointer to .**  
ffa0: 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63           newly c
ffb0: 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
ffc0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
ffd0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
ffe0: 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
fff0: 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
10000 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ed, .**         
10010 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20    or it returns 
10020 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e  NULL if it is un
10030 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20  able to fulfill 
10040 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
10050 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65  ** {F17304}  The
10060 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10070 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
10080 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
10090 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
100a0 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
100b0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
100c0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
100d0 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
100e0 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
100f0 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
10100 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
10110 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
10120 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
10130 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
10140 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10150 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
10160 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
10170 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
10180 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  se..**.** {F1730
10190 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
101a0 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
101b0 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
101c0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46   no-op..**.** {F
101d0 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
101e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
101f0 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
10200 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
10210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
10220 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10230 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  (N)]..**.** {F17
10240 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
10250 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10260 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
10270 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
10280 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
10290 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
102a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d  ..**.** {F17315}
102b0 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
102c0 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
102d0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
102e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
102f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
10300 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10310 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
10320 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10330 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
10340 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
10350 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   needs..**.** {F
10360 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
10370 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
10380 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10390 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
103a0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
103b0 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
103c0 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
103d0 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
103e0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
103f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
10400 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
10410 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
10420 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
10430 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
10440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10450 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
10460 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
10470 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
10480 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
10490 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
104a0 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
104b0 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20   into the newly 
104c0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20  allocated.**    
104d0 20 20 20 20 20 20 20 77 68 65 72 65 20 4b 20 69         where K i
104e0 73 20 74 68 65 20 6c 65 73 73 6f 72 20 6f 66 20  s the lessor of 
104f0 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f  N and the size o
10500 66 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a  f the buffer P..
10510 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20  **.** {F17322}  
10520 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
10530 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
10540 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
10550 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
10560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
10570 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
10580 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  r P..**.** {F173
10590 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
105a0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
105b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
105c0 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
105d0 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
105e0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
105f0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ased..**.** LIMI
10600 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
10610 55 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  U17350}  The poi
10620 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
10630 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
10640 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
10650 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
10660 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
10670 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
10680 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62  lse a pointer ob
10690 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
106a0 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
106b0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
106c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
106d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
106e0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
106f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
10700 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  ot been released
10710 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d  ..**.** {U17351}
10720 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10730 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
10740 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
10750 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20  t of .**        
10760 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65     a block of me
10770 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
10780 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
10790 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
107a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65     [sqlite3_free
107b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
107c0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a  realloc()]..**.*
107d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
107e0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
107f0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
10800 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
10810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
10820 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
10830 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10840 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
10850 69 73 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a  istics {F17370}.
10860 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
10870 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
10880 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
10890 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
108a0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
108b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
108c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
108d0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
108e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
108f0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
10900 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
10910 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69  m included withi
10920 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a  n the SQLite..**
10930 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10940 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54  **.** {F17371} T
10950 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
10960 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
10970 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
10980 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
10990 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65  r of bytes of me
109a0 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
109b0 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20  utstanding .**  
109c0 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65          (malloce
109d0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
109e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d  ..**.** {F17373}
109f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10a00 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
10a10 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
10a20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
10a30 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
10a40 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
10a50 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20  ry_used()] .**  
10a60 20 20 20 20 20 20 20 20 73 69 6e 63 65 20 74 68          since th
10a70 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
10a80 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
10a90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20  .**.** {F17374} 
10aa0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
10ab0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
10ac0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
10ad0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
10ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10af0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
10b00 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
10b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
10b20 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
10b30 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
10b40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
10b50 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
10b60 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76        but not ov
10b70 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
10b80 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
10b90 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
10ba0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  y.**          ro
10bb0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
10bc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
10bd0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20  ay call..** .** 
10be0 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d  {F17375} The mem
10bf0 6f 72 79 20 68 69 67 68 77 61 74 65 72 20 6d 61  ory highwater ma
10c00 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
10c10 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
10c20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
10c30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
10c40 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
10c50 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
10c60 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
10c70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
10c80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
10c90 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76   is true.  The v
10ca0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
10cb0 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [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 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
10ce0 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
10cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
10d00 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
10d10 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
10d20 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
10d30 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
10d40 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
10d50 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
10d60 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
10d70 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
10d80 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
10d90 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
10da0 74 6f 72 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a  tor {F17390}.**.
10db0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
10dc0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
10dd0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
10de0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
10df0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
10e00 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
10e10 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
10e20 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
10e30 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
10e40 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
10e50 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
10e60 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
10e70 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
10e80 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
10e90 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
10ea0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
10eb0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
10ec0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
10ed0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
10ee0 70 70 6c 69 61 74 69 6f 6e 73 20 74 6f 20 61 63  ppliations to ac
10ef0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
10f00 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
10f10 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
10f20 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
10f30 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
10f40 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
10f50 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
10f60 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10f70 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
10f80 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
10f90 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
10fa0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
10fb0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
10fc0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
10fd0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
10fe0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
10ff0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
11000 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
11010 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
11020 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
11030 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
11040 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
11050 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
11060 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
11070 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
11080 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
11090 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
110a0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
110b0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
110c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
110d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20  .**.** {F17392} 
110e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e  The [sqlite3_ran
110f0 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e  domness(N,P)] in
11100 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e  terface writes N
11110 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
11120 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69        high-quali
11130 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
11140 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
11150 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69   P..*/.void sqli
11160 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
11170 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
11180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11190 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
111a0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
111b0 62 61 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a  backs {F12500}.*
111c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
111d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
111e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
111f0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
11200 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
11220 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
11230 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11240 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
11250 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
11260 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
11270 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
11280 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
11290 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
112a0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
112b0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
112c0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
112d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
112e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
112f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
11300 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  .  At various.**
11310 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
11320 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
11330 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
11340 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
11350 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
11360 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
11370 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11380 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
11390 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
113a0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
113b0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
113c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
113d0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
113e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
113f0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
11400 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
11410 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
11420 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
11430 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
11440 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
11450 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
11460 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
11470 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
11480 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
11490 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
114a0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
114b0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
114c0 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68  n error.   If th
114d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
114e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
114f0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
11500 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
11510 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
11520 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
11530 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  ENY].** then [sq
11540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11550 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
11560 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
11570 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
11580 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
11590 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
115a0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
115b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
115c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
115d0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
115e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
115f0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
11600 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
11610 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
11620 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
11630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
11640 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
11650 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
11660 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
11670 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
11680 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
11690 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
116a0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
116b0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
116c0 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
116d0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
116e0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
116f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
11700 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
11710 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
11720 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
11730 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
11740 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
11750 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
11760 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
11770 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
11780 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
11790 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
117a0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
117b0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
117c0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
117d0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
117e0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
117f0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
11800 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
11810 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
11820 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
11830 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
11840 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
11850 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
11860 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11870 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
11880 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72  ** the third par
11890 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
118a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
118b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
118c0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
118d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
118e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
118f0 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c  integer .** [SQL
11900 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
11910 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
11920 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
11930 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
11940 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
11950 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
11960 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72  ugh sixth.** par
11970 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
11980 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
11990 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
119a0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
119b0 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20   .** additional 
119c0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
119d0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
119e0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
119f0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
11a00 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
11a10 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
11a20 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
11a30 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
11a40 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a   an untrusted.**
11a50 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
11a60 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
11a70 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f  statements do no
11a80 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
11a90 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65  data.** that the
11aa0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
11ab0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
11ac0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72  t they do not tr
11ad0 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20  y to.** execute 
11ae0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
11af0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
11b00 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
11b10 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
11b20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
11b30 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
11b40 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
11b50 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
11b60 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
11b70 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
11b80 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
11b90 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
11ba0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
11bb0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
11bc0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
11bd0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
11be0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
11bf0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
11c00 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
11c10 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
11c20 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
11c30 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
11c40 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
11c50 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
11c60 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
11c70 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
11c80 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
11c90 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
11ca0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
11cb0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
11cc0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
11cd0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
11ce0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
11cf0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
11d00 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
11d10 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
11d20 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
11d30 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
11d40 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
11d50 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
11d60 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
11d70 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
11d80 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
11d90 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
11da0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
11db0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
11dc0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
11dd0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
11de0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11df0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
11e00 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
11e10 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
11e20 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
11e30 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
11e40 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
11e50 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
11e60 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
11e70 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
11e80 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
11e90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11ea0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
11eb0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a  d only during .*
11ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
11ed0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
11ee0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
11ef0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
11f00 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
11f10 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
11f20 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
11f30 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
11f40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11f50 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20  ** {F12501} The 
11f60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
11f70 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20  horizer(D,...)] 
11f80 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
11f90 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  ers a.**        
11fa0 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
11fb0 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62  lback with datab
11fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
11fd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d  ..**.** {F12502}
11fe0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
11ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
12000 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
12010 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20  ments are.**    
12020 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70        being comp
12030 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  iled.**.** {F125
12040 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  03} If the autho
12050 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
12060 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65  eturns any value
12070 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
12080 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
12090 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
120a0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
120b0 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20  _DENY] then.**  
120c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
120d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
120e0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
120f0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
12100 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
12110 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12120 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
12130 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a  ll fail with an.
12140 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
12150 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
12160 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70   code and an app
12170 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
12180 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essage..**.** {F
12190 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20  12504} When the 
121a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
121b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
121c0 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
121d0 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ration.**       
121e0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20     described is 
121f0 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a  coded normally..
12200 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57  **.** {F12505} W
12210 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
12220 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
12230 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
12240 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ], the.**       
12250 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
12260 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
12270 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
12280 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20  t caused the.** 
12290 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69           authori
122a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  zer callback to 
122b0 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a  run shall fail.*
122c0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
122d0 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  an [SQLITE_ERROR
122e0 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
122f0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
12300 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  e.**          ex
12310 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63  plaining that ac
12320 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a  cess is denied..
12330 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49  **.** {F12506} I
12340 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
12350 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
12360 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12370 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
12380 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
12390 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
123a0 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72  ] and the author
123b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
123c0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
123d0 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45    [SQLITE_IGNORE
123e0 5d 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61  ] then the prepa
123f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
12400 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a   constructed to.
12410 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65  **          inse
12420 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
12430 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
12440 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
12450 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
12460 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65           been re
12470 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
12480 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
12490 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ned..**.** {F125
124a0 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  07} If the autho
124b0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
124c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
124d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
124e0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
124f0 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e  back) is anythin
12500 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
12510 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e  LITE_READ], then
12520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
12530 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45  eturn of [SQLITE
12540 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65  _IGNORE] has the
12550 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
12560 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a  [SQLITE_DENY]. .
12570 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54  **.** {F12510} T
12580 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12590 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
125a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
125b0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
125c0 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64         the third
125d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
125e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
125f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
12600 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  erface..**.** {F
12610 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e  12511} The secon
12620 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
12630 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
12640 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20  n integer .**   
12650 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
12660 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
12670 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
12680 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
12690 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
126a0 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72      to be author
126b0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
126c0 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74  512} The third t
126d0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
126e0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
126f0 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20  allback are.**  
12700 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
12710 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
12720 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a  that contain .**
12730 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69            additi
12740 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f  onal details abo
12750 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
12760 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
12770 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45  **.** {F12520} E
12780 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
12790 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
127a0 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73  zer()] overrides
127b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
127c0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
127d0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
127e0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  izer..**.** {F12
127f0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
12800 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
12810 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
12820 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
12830 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
12840 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  ed..**.** {F1252
12850 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
12860 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
12870 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
12880 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12890 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
128a0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
128b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
128c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
128d0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
128e0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
128f0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
12900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
12910 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
12920 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a   Codes {F12590}.
12930 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
12940 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12950 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
12960 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12970 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
12980 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
12990 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
129a0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
129b0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
129c0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
129d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
129e0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
129f0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
12a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
12a10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
12a20 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
12a30 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
12a40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
12a50 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
12a60 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
12a70 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
12a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
12a90 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
12aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
12ab0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
12ac0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
12ad0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
12ae0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
12af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12b00 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
12b10 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d  n Codes {F12550}
12b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
12b30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12b40 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
12b50 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
12b60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
12b70 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
12b80 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
12b90 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
12ba0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
12bb0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
12bc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
12bd0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
12be0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
12bf0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
12c00 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
12c10 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
12c20 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
12c30 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
12c40 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
12c50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12c60 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
12c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
12c80 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
12c90 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
12ca0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
12cb0 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
12cc0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
12cd0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
12ce0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
12cf0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
12d00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
12d10 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
12d20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
12d30 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
12d40 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
12d50 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
12d60 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
12d70 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
12d80 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
12d90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
12da0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
12db0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
12dc0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
12dd0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
12de0 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
12df0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
12e00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12e10 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
12e20 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
12e30 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
12e40 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
12e50 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
12e60 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
12e70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
12e80 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
12e90 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
12ea0 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  m .** top-level 
12eb0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
12ec0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
12ed0 2a 20 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73  * {F12551} The s
12ee0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12ef0 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20  to an .**       
12f00 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
12f10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
12f20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12f30 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e   is always an in
12f40 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
12f50 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
12f60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
12f70 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
12f80 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
12f90 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
12fa0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
12fb0 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65  .** {F12552} The
12fc0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
12fd0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a  ameters to the .
12fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
12ff0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
13000 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74  zer | authorizat
13010 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ion callback fun
13020 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
13030 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d     will be param
13040 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
13050 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
13060 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53   .**          [S
13070 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
13080 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73  horizer code] is
13090 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
130a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ond parameter..*
130b0 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68  *.** {F12553} Th
130c0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
130d0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
130e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
130f0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
13100 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13110 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  ] is the name.**
13120 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
13130 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70   database (examp
13140 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  le: "main", "tem
13150 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70  p", etc.) if app
13160 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  licable..**.** {
13170 46 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20  F12554} The 6th 
13180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
131a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
131b0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
131c0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
131d0 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
131e0 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72      of the inner
131f0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
13200 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
13210 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
13220 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
13230 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
13240 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
13250 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
13260 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
13270 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
13280 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
13290 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
132a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
132c0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
132d0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
132e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
132f0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
13300 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
13310 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
13320 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
13340 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
13350 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
13360 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
13370 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
13390 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
133a0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
133b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
133c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
133d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
133e0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
133f0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
13400 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13410 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13420 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13430 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
13440 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
13450 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
13460 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
13470 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13480 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
13490 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
134a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
134b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
134c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
134d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
134e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
134f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
13500 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13510 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
13520 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
13530 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
13540 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13550 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13560 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
13570 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
13580 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13590 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
135a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
135b0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
135c0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
135d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
135e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
135f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13600 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
13610 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
13620 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
13630 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13640 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13650 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
13660 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
13670 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
13680 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13690 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
136a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
136b0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
136c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
136d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
136e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
136f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
13700 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
13710 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
13720 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
13730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13740 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
13750 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
13760 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
13770 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13790 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
137a0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
137b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
137c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
137d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
137e0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
137f0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
13800 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
13810 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
13830 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
13840 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
13850 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
13860 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
13880 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
13890 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
138a0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
138b0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
138c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
138d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
138e0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
138f0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
13900 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
13910 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
13920 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
13930 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
13940 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
13950 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13960 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
13970 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
13980 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
13990 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
139a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
139b0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
139c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
139d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
139e0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
139f0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
13a00 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
13a10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
13a20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
13a30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13a40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13a50 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
13a60 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
13a70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
13a80 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
13a90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13aa0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
13ab0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
13ac0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
13ad0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
13ae0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13af0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
13b00 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
13b10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
13b20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13b30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13b40 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
13b50 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
13b60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13b80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13b90 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
13ba0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
13bb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13bc0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
13bd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13be0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
13bf0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
13c00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
13c10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
13c20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13c30 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
13c40 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
13c50 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
13c60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13c70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13c80 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
13c90 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
13ca0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
13cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13cc0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
13cd0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
13ce0 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12280}.**.** T
13cf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
13d00 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
13d10 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
13d20 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
13d30 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
13d40 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
13d50 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
13d60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  tements..**.** T
13d70 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
13d80 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
13d90 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
13da0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
13db0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
13dc0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
13dd0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
13de0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
13df0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  _step()]..** The
13e00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13e10 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  s a UTF-8 render
13e20 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ing of the SQL s
13e30 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a  tatement text.**
13e40 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
13e50 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
13e60 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74  xecuting.  Addit
13e70 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
13e80 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
13e90 20 74 72 69 67 67 65 72 73 75 62 70 72 6f 67 72   triggersubprogr
13ea0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
13eb0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
13ec0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
13ed0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
13ee0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
13ef0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
13f00 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  igger..** .** Th
13f10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
13f20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
13f30 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
13f40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
13f50 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
13f60 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
13f70 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
13f80 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
13f90 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
13fa0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
13fb0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
13fc0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
13fd0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
13fe0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
13ff0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
14000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14010 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73  profile() API is
14020 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
14030 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
14040 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62  al and.** is sub
14050 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
14060 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66  r removal in a f
14070 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a  uture release..*
14080 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72  *.** The trigger
14090 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75   reporting featu
140a0 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20  re of the trace 
140b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73  callback is cons
140c0 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69  idered.** experi
140d0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
140e0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
140f0 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  or removal in fu
14100 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
14110 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * Future version
14120 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
14130 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74  t also add new t
14140 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  race callback .*
14150 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a  * invocations..*
14160 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14170 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20  .**.** {F12281} 
14180 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
14190 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
141a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   by [sqlite3_tra
141b0 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  ce()] is.**     
141c0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
141d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
141e0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
141f0 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
14200 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
14210 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
14220 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
14230 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
14240 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {F12282} Each ca
14250 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
14260 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65  race()] override
14270 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79  s the previously
14280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
14290 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61  istered trace ca
142a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  llback..**.** {F
142b0 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72  12283} A NULL tr
142c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73  ace callback dis
142d0 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a  ables tracing..*
142e0 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68  *.** {F12284} Th
142f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14300 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
14310 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
14320 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
14330 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
14340 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
14350 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
14360 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
14370 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20  ** {F12285} The 
14380 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14390 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
143a0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
143b0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
143c0 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69  inated UTF8 stri
143d0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
143e0 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a  e original text.
143f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
14400 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14410 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65   as it was passe
14420 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f  d into [sqlite3_
14430 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
14440 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
14450 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
14460 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69  an SQL comment i
14470 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65  ndicating the be
14480 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ginning.**      
14490 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72      of a trigger
144a0 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a   subprogram..**.
144b0 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20  ** {F12287} The 
144c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
144d0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
144e0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
144f0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
14500 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61  *          as ea
14510 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
14520 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a   finishes..**.**
14530 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66 69   {F12288} The fi
14540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14550 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
14560 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
14570 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
14580 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
14590 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
145a0 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  file()]..**.** {
145b0 46 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f  F12289} The seco
145c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
145d0 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
145e0 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20  back is a.**    
145f0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
14600 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
14610 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  ng that contains
14620 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65   the complete te
14630 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  xt of.**        
14640 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d    the SQL statem
14650 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72  ent as it was pr
14660 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69  ocessed by [sqli
14670 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14680 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
14690 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e   the equivalent.
146a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20  .**.** {F12290} 
146b0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
146c0 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
146d0 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  le  callback is 
146e0 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
146f0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
14700 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
14710 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
14720 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
14730 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
14740 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
14750 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
14760 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76   to finish..*/.v
14770 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
14780 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
14790 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
147a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
147b0 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
147c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
147d0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
147e0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
147f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
14800 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
14810 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
14820 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
14830 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b  ress Callbacks {
14840 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12910}.**.** Th
14850 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
14860 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
14870 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
14880 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
14890 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
148a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
148b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
148c0 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
148d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
148e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
148f0 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
14900 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14910 28 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c  ()].   An exampl
14920 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a  e use for this .
14930 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
14940 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
14950 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
14960 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
14970 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  * If the progres
14980 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
14990 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
149a0 20 6f 70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20   opertion is.** 
149b0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
149c0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
149d0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
149e0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
149f0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
14a00 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  I dialog box..**
14a10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
14a20 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54  **.** {F12911} T
14a30 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
14a40 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
14a50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  by [sqlite3_prog
14a60 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
14a70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
14a80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
14a90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
14aa0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
14ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
14ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
14ad0 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
14ae0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14af0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
14b00 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
14b10 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
14b20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
14b30 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
14b40 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14b50 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20  ent to .**      
14b60 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
14b70 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
14b80 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72  r()] call that r
14b90 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
14ba0 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61        the callba
14bb0 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20  ck.  <todo>What 
14bc0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
14bd0 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  n 1?</todo>.**.*
14be0 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70  * {F12913} The p
14bf0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
14c00 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74   itself is ident
14c10 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69  ified by the thi
14c20 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rd.**          a
14c30 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
14c40 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14c50 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  dler()]..**.** {
14c60 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72  F12914} The four
14c70 74 68 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c  th argument [sql
14c80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
14c90 6e 64 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a  ndler()] is a.**
14ca0 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70  *         void p
14cb0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
14cc0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
14cd0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
14ce0 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
14cf0 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
14d00 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
14d10 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
14d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14d30 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
14d40 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
14d50 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65      N opcodes be
14d60 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a  ing executed,.**
14d70 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
14d80 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
14d90 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
14da0 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  voked. {END}.** 
14db0 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65  .** {F12916} Eve
14dc0 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ry call to [sqli
14dd0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14de0 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
14df0 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61      overwrites a
14e00 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ny previously re
14e10 67 69 73 74 65 72 65 20 70 72 6f 67 72 65 73 73  gistere progress
14e20 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
14e30 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {F12917} If the 
14e40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
14e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
14e60 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
14e70 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
14e80 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
14e90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38  d..**.** {F12918
14ea0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
14eb0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
14ec0 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
14ed0 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
14ee0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
14ef0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
14f00 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
14f10 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
14f20 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  alled..*/.void s
14f30 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
14f40 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14f50 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
14f60 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
14f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
14f80 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
14f90 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
14fa0 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12700}.**.** 
14fb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
14fc0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
14fd0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
14fe0 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76  e name.** is giv
14ff0 65 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61  en by the filena
15000 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  me argument..** 
15010 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
15020 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
15030 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
15040 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
15050 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
15060 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
15070 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69  d as UTF-16.** i
15080 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
15090 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
150a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
150b0 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d  ** An [sqlite3*]
150c0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
150d0 6c 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ly returned in *
150e0 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66  ppDb, even.** if
150f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
15100 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
15110 70 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69  ption is if SQLi
15120 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  te is unable.** 
15130 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
15140 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
15150 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
15160 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20   a NULL will.** 
15170 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
15180 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
15190 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
151a0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
151b0 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  ct..** If the da
151c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
151d0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
151e0 29 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  ).** successfull
151f0 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  y, then [SQLITE_
15200 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
15210 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a    Otherwise an.*
15220 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  * error code is 
15230 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
15240 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
15250 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
15260 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f  _errmsg16()]  ro
15270 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
15280 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
15290 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
152a0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
152b0 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
152c0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
152d0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
152e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
152f0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73  e UTF-8 if.** [s
15300 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
15310 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
15320 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  v2()] is called 
15330 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
15340 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
15350 20 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74   order if [sqlit
15360 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
15370 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
15380 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
15390 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
153a0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
153b0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
153c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
153d0 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
153e0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
153f0 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  sed by passing i
15400 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
15410 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
15420 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
15430 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
15440 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
15450 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
15460 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c   works like [sql
15470 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a  ite3_open()] .**
15480 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
15490 61 63 63 63 65 70 74 73 20 74 77 6f 20 61 64 64  acccepts two add
154a0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
154b0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
154c0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
154d0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
154e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
154f0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
15500 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e  ter can be.** on
15510 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  e of:.**.** <ol>
15520 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
15530 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
15540 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
15550 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
15560 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
15570 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
15580 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
15590 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f  N_CREATE].** </o
155a0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  l>.**.** The fir
155b0 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74  st value opens t
155c0 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61 64  he database read
155d0 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68  -only. .** If th
155e0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
155f0 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65  not previously e
15600 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
15610 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
15620 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e  he second option
15630 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61   opens.** the da
15640 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
15650 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
15660 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
15670 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a  eading only if.*
15680 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  * if the file is
15690 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
156a0 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73  .  In either cas
156b0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  e the database.*
156c0 2a 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  * must already e
156d0 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72  xist or an error
156e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
156f0 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a  he third option.
15700 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ** opens the dat
15710 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
15720 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e  g and writing an
15730 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20  d creates it if 
15740 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61  it does.** not a
15750 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a  lready exist..**
15760 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f   The third optio
15770 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74  ns is behavior t
15780 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
15790 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ed for [sqlite3_
157a0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  open()].** and [
157b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
157c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
157d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
157e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
157f0 32 28 29 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20  2()] is not one 
15800 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
15810 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
15820 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
15830 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
15840 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
15850 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
15860 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
15870 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65  private.** in-me
15880 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
15890 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
158a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
158b0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  is in-memory.** 
158c0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
158d0 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64 61  nish when the da
158e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
158f0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
15900 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ture.** version 
15910 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
15920 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
15930 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
15940 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74  ilenames.** that
15950 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
15960 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 20  ":" character.  
15970 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
15980 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20  d that .** when 
15990 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
159a0 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20  ame really does 
159b0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a  begin with.** ":
159c0 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66 69  " that you prefi
159d0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
159e0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c  ith a pathname l
159f0 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61  ike "./" to.** a
15a00 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
15a10 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
15a20 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
15a30 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
15a40 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61   private tempora
15a50 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
15a60 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
15a70 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72  reated.  This pr
15a80 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
15a90 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
15aa0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
15ab0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
15ac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15ad0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
15ae0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
15af0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
15b00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
15b10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
15b30 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
15b40 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
15b50 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69  ing system .** i
15b60 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68  nterface that th
15b70 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
15b80 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
15b90 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a   use.  If the.**
15ba0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15bb0 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  r is a NULL poin
15bc0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
15bd0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
15be0 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20  s].** object is 
15bf0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  used..**.** <b>N
15c00 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75  ote to windows u
15c10 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
15c20 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
15c30 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
15c40 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71  gument.** of [sq
15c50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
15c60 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
15c70 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54  v2()] must be UT
15c80 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
15c90 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
15ca0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15cb0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
15cc0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
15cd0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
15ce0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
15cf0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
15d00 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
15d10 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b  g them into.** [
15d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
15d30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15d40 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
15d50 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15d60 7b 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71  {F12701} The [sq
15d70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
15d80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15d90 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
15da0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15db0 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
15dc0 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a  s create a new.*
15dd0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
15de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15df0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
15e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
15e10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67   database file g
15e20 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69  iven in their fi
15e30 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
15e40 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68  *.** {F12702} Th
15e50 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
15e60 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
15e70 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20  ed as UTF-8.**  
15e80 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c          for [sql
15e90 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
15ea0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15eb0 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
15ec0 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  16.**          i
15ed0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
15ee0 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
15ef0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
15f00 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41  **.** {F12703} A
15f10 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
15f20 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15f30 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
15f40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
15f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
15f60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15f70 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69  ()] writes a poi
15f80 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
15f90 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
15fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15fb0 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a  into *ppDb..**.*
15fc0 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b  * {F12704} The [
15fd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
15fe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
15ff0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
16000 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
16010 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
16020 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ces return [SQLI
16030 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63  TE_OK] upon succ
16040 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess,.**         
16050 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
16060 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
16070 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
16080 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64  * {F12706} The d
16090 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
160a0 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
160b0 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
160c0 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
160d0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28    [sqlite3_open(
160e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
160f0 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62  pen_v2()] will b
16100 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  e UTF-8..**.** {
16110 46 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61  F12707} The defa
16120 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
16130 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
16140 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
16150 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
16160 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16170 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ] will be UTF-16
16180 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d  ..**.** {F12709}
16190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
161a0 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  en(F,D)] interfa
161b0 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
161c0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
161d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
161e0 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65  (F,D,G,0)] where
161f0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
16200 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
16210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
16220 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f  DWRITE]|[SQLITE_
16230 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a  OPEN_CREATE]..**
16240 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20  .** {F12711} If 
16250 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
16260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16270 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
16280 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
16290 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
162a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
162b0 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65  ADONLY] then the
162c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
162d0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
162e0 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79  for reading only
162f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d  ..**.** {F12712}
16300 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
16310 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16320 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
16330 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
16340 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
16350 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
16360 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65  N_READWRITE] the
16370 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
16380 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
16390 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64       reading and
163a0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
163b0 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61  ible, or for rea
163c0 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65  ding only if the
163d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
163e0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
163f0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
16400 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a  ating system..**
16410 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20  .** {F12713} If 
16420 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
16430 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16440 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d  (v2(F,D,G,V)] om
16450 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  its the.**      
16460 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16480 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
16490 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
164a0 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
164b0 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  sly exist, an er
164c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
164d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20  .**.** {F12714} 
164e0 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
164f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
16500 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen(v2(F,D,G,V)]
16510 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
16520 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
16530 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
16540 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
16550 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
16560 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
16570 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
16580 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74   then an attempt
16590 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61   is made to crea
165a0 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  te and.**       
165b0 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68     initialize th
165c0 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a  e database..**.*
165d0 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68  * {F12717} If th
165e0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
165f0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
16600 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
16610 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
16620 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
16630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
16640 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
16650 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a  hen an private,.
16660 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
16670 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79  meral, in-memory
16680 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
16690 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
166a0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20  nection..**     
166b0 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51       <todo>Is SQ
166c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
166d0 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  |SQLITE_OPEN_REA
166e0 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a  DWRITE required.
166f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73  **          in s
16700 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16710 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
16720 46 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66  F12719} If the f
16730 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  ilename is NULL 
16740 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
16750 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
16760 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
16770 65 70 68 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69  ephermeral on-di
16780 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
16790 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
167a0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
167b0 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
167c0 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
167d0 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
167e0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
167f0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
16800 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
16810 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20  ** {F12721} The 
16820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16830 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
16840 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73   .**          [s
16850 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
16860 2c 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73  ,D,G,V)] will us
16870 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
16880 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20    [sqlite3_vfs] 
16890 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65  object identifie
168a0 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d  d by the V param
168b0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  eter, or.**     
168c0 20 20 20 20 20 74 68 65 20 64 65 66 61 75 6c 74       the default
168d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
168e0 62 6a 65 63 74 20 69 73 20 56 20 69 73 20 61 20  bject is V is a 
168f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
16900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
16910 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
16920 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
16930 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
16940 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
16950 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
16960 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
16970 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16980 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
16990 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
169a0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
169b0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
169c0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
169d0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
169e0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
169f0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16a00 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
16a10 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
16a20 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
16a30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
16a40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
16a50 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
16a60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
16a70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
16a80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16a90 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
16aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
16ab0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
16ac0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
16ad0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
16ae0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
16af0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
16b00 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
16b10 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20  es And Messages 
16b20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12800}.**.** T
16b30 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
16b40 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
16b50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
16b60 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ic.** [SQLITE_OK
16b70 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20   | result code] 
16b80 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16b90 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
16ba0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
16bb0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
16bc0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
16bd0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
16be0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
16bf0 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64  h [sqlite3] hand
16c00 6c 65 20 27 64 62 27 2e 20 49 66 20 61 20 70 72  le 'db'. If a pr
16c10 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
16c20 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d  led but the.** m
16c30 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
16c40 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
16c50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
16c60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
16c70 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  code().** is und
16c80 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
16c90 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
16ca0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
16cb0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
16cc0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
16cd0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
16ce0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
16cf0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
16d00 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
16d10 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
16d20 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
16d30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
16d40 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
16d50 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
16d60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
16d70 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
16d80 77 6f 72 72 79 20 77 69 74 68 20 66 72 65 65 69  worry with freei
16d90 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
16da0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
16db0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
16dc0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
16dd0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
16de0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
16df0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
16e00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
16e10 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
16e20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
16e30 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68 65  .** {F12801} The
16e40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
16e50 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
16e60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
16e70 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
16e80 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
16e90 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
16ea0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16eb0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
16ec0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16ed0 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  de].**          
16ee0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
16ef0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
16f00 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f  erface call asso
16f10 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ciated.**       
16f20 20 20 20 77 69 74 68 20 5b 64 61 74 61 62 61 73     with [databas
16f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
16f40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20  .**.** {F12803} 
16f50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
16f60 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c  msg(D)] and [sql
16f70 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29  ite3_errmsg16(D)
16f80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
16f90 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
16fa0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
16fb0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
16fc0 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ibes.**         
16fd0 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68   the error in th
16fe0 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c  e mostly recentl
16ff0 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61  y failed interfa
17000 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20  ce call,.**     
17010 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20       encoded as 
17020 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
17030 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
17040 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37  y..**.** {F12807
17050 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
17060 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
17070 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
17080 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
17090 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
170a0 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
170b0 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
170c0 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
170d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d  ..**.** {F12808}
170e0 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
170f0 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
17100 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
17110 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
17120 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
17130 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
17140 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
17150 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
17160 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
17170 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
17180 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
17190 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
171a0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
171b0 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
171c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
171d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30  )]..**.** {F1280
171e0 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68  9} Interfaces th
171f0 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63  at are not assoc
17200 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
17210 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  cific.**        
17220 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
17230 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65  ection] (example
17240 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  s:.**          [
17250 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
17260 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
17270 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
17280 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  he()].**        
17290 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20    do not change 
172a0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
172b0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
172c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
172d0 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
172e0 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
172f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
17300 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
17310 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
17320 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
17330 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
17340 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
17350 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
17360 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
17370 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17380 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
17390 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
173a0 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  13000}.** KEYWOR
173b0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
173c0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
173d0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
173e0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
173f0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
17400 72 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65  represent single
17410 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
17420 20 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74    This.** object
17430 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
17440 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
17450 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
17460 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64   a .** "compiled
17470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
17480 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
17490 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a  statement"..** .
174a0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
174b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
174c0 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
174d0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
174e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
174f0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
17500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17510 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
17520 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
17530 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
17540 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
17550 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
17560 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ers using.**    
17570 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
17580 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
17590 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73  ind_* interfaces
175a0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  ]..** <li> Run t
175b0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
175c0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
175d0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
175e0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
175f0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
17600 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
17610 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
17620 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
17630 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
17640 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
17650 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
17660 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
17670 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
17680 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
17690 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
176a0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
176b0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
176c0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
176d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
176e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
176f0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
17700 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
17710 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
17720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
17730 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31  -time Limits {F1
17740 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2760}.**.** This
17750 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
17760 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
17770 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
17780 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
17790 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
177a0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
177b0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
177c0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
177d0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
177e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
177f0 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
17800 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
17810 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
17820 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
17830 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
17840 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
17850 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
17860 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
17870 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
17880 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
17890 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
178a0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
178b0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
178c0 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
178d0 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
178e0 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
178f0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
17900 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
17910 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
17920 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
17930 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
17940 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
17950 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
17960 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
17970 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
17980 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 2d   compile-time C-
17990 70 72 65 70 72 6f 63 65 73 73 20 6d 61 63 72 6f  preprocess macro
179a0 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41   named SQLITE_MA
179b0 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22  X_XYZ..** (The "
179c0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
179d0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
179e0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20  to "_MAX_".).** 
179f0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
17a00 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
17a10 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
17a20 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
17a30 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
17a40 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
17a50 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  per limit..**.**
17a60 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73   Run time limits
17a70 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
17a80 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
17a90 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
17aa0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
17ab0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
17ac0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
17ad0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
17ae0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
17af0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
17b00 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
17b10 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
17b20 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
17b30 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20  a.** webbrowser 
17b40 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
17b50 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
17b60 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
17b70 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
17b80 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
17b90 6c 65 64 20 62 79 20 6a 61 76 61 73 63 72 69 70  led by javascrip
17ba0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
17bb0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
17bc0 20 74 68 65 20 69 6e 74 65 72 6e 65 74 2e 20 20   the internet.  
17bd0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
17be0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
17bf0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
17c00 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
17c10 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
17c20 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
17c30 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
17c40 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
17c50 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
17c60 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
17c70 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
17c80 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 68 2e 20  vice.** attach. 
17c90 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
17ca0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
17cb0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
17cc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17cd0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
17ce0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
17cf0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
17d00 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17d10 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
17d20 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
17d30 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
17d40 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
17d50 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
17d60 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
17d70 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  GMA]..**.** This
17d80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 75   interface is cu
17d90 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
17da0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
17db0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 0a 2a  and is subject.*
17dc0 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  * to change or r
17dd0 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75 74 20 70  emoval without p
17de0 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a  rior notice..**.
17df0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17e00 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41 20  *.** {F12762} A 
17e10 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
17e20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
17e30 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
17e40 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  V is.**         
17e50 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65   positive change
17e60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
17e70 20 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73    limit on the s
17e80 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
17e90 20 43 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20   C in [database 
17ea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
17eb0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
17ec0 20 6c 65 73 73 6f 72 20 6f 66 20 56 20 61 6e 64   lessor of V and
17ed0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
17ee0 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a  bound on the siz
17ef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17f00 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61   C that is set a
17f10 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a  t compile-time..
17f20 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 34 7d 20 41  **.** {F12764} A
17f30 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
17f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
17f50 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
17f60 20 56 20 69 73 20 7a 65 72 6f 0a 2a 2a 20 20 20   V is zero.**   
17f70 20 20 20 20 20 20 20 63 68 61 6e 67 65 73 20 74         changes t
17f80 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
17f90 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
17fa0 74 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  t C in.**       
17fb0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
17fc0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 62 65  nection] D to be
17fd0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
17fe0 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a  bound on the siz
17ff0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
18000 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61   C that is set a
18010 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a  t compile-time..
18020 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41  **.** {F12766} A
18030 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
18040 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
18050 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
18060 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   V is negative.*
18070 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65  *          leave
18080 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 5b  s the state of [
18090 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
180a0 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
180b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d  ..**.** {F12769}
180c0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
180d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
180e0 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
180f0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
18100 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
18110 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
18120 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
18130 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20   C in.**        
18140 20 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63    in [database c
18150 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20  onnection] D as 
18160 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20  it was prior to 
18170 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74  the call..*/.int
18180 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
18190 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
181a0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
181b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
181c0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
181d0 74 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30  tegories {F12790
181e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
181f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
18200 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
18210 73 7d 0a 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20  s}.** .** These 
18220 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
18230 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73   various aspects
18240 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   of a [database 
18250 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
18260 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74  hat can be limit
18270 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61  ed in size by ca
18280 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18290 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
182a0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
182b0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
182c0 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
182d0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
182e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
182f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
18300 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
18310 7a 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72  ze of any.** str
18320 69 6e 67 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74  ing or blob or t
18330 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
18340 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18350 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
18360 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18370 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
18380 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
18390 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
183a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
183b0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
183c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
183d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
183e0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
183f0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
18400 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
18410 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68  f a SELECT or th
18420 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18430 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
18440 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
18450 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
18460 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
18470 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
18490 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
184a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
184b0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
184c0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
184d0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a  xpression.</dd>.
184e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
184f0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
18500 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
18510 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18520 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
18530 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
18540 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
18550 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18560 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
18570 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
18580 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18590 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
185a0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
185b0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
185c0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
185d0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
185e0 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
185f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18600 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
18610 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18620 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18630 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
18640 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  function.</dd>.*
18650 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18660 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
18670 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18680 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18690 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
186a0 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ses.</dd>.**.** 
186b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
186c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
186d0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
186e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
186f0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
18700 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
18710 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c  he LIKE or.** GL
18720 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  OB operators.</d
18730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18740 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
18750 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
18760 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18770 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
18780 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
18790 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
187a0 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
187b0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
187c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
187e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
187f0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
18800 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
18810 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18820 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
18830 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
18840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18850 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
18860 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
18870 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
18880 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18890 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
188a0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
188b0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
188c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
188d0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
188e0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
188f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
18900 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
18910 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
18920 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
18930 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
18940 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
18950 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
18960 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
18970 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
18980 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
18990 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
189a0 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
189b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
189c0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
189d0 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
189e0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
189f0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
18a00 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
18a10 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
18a20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
18a30 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
18a40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
18a50 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  . .**.** The fir
18a60 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22  st argument "db"
18a70 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65   is an [database
18a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a   connection] .**
18a90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
18aa0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
18ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
18ac0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
18ad0 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
18ae0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a  te3_open16()]. .
18af0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
18b00 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
18b10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
18b20 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
18b30 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
18b40 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
18b50 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
18b60 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
18b70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18b80 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
18b90 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
18ba0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
18bb0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
18bc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18bd0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20  .** use UTF-16. 
18be0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
18bf0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
18c00 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
18c10 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
18c20 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
18c30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
18c40 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
18c50 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
18c60 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
18c70 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
18c80 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
18c90 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
18ca0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
18cb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
18cc0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
18cd0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
18ce0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
18cf0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
18d00 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
18d10 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
18d20 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
18d30 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
18d40 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
18d50 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
18d60 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
18d70 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
18d80 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
18d90 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
18da0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
18db0 65 20 68 61 64 20 62 79 20 70 61 73 73 69 6e 67  e had by passing
18dc0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
18dd0 74 65 72 20 74 68 61 74 20 0a 2a 2a 20 69 73 20  ter that .** is 
18de0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
18df0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
18e00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
18e10 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
18e20 3e 20 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  > .** the nul-te
18e30 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b  rminator bytes.{
18e40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  END}.**.** *pzTa
18e50 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
18e60 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
18e70 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
18e80 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
18e90 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
18ea0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
18eb0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
18ec0 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72 73  ompiles the firs
18ed0 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
18ee0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
18ef0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
18f00 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
18f10 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
18f20 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
18f30 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
18f40 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
18f50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
18f60 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
18f70 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
18f80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
18f90 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
18fa0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
18fb0 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74  ppStmt is.** set
18fc0 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
18fd0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
18fe0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
18ff0 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73   the input.** is
19000 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e   and empty strin
19010 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
19020 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
19030 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
19040 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {U13018} The cal
19050 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
19060 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
19070 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a  r deleting the.*
19080 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  * compiled SQL s
19090 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
190a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
190b0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
190c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
190d0 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
190e0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
190f0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
19100 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
19110 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
19120 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19130 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
19140 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
19150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19160 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
19170 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
19180 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
19190 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
191a0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
191b0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
191c0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
191d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
191e0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
191f0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
19200 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
19210 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
19220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19230 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
19240 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
19250 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
19260 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
19270 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67   of the .** orig
19280 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b  inal SQL text. {
19290 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73  END} This causes
192a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
192b0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
192c0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
192d0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
192e0 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
192f0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
19300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
19310 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
19320 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
19330 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
19340 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
19350 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
19360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19370 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
19380 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
19390 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
193a0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
193b0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
193c0 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
193d0 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
193e0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
193f0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
19400 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
19410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19420 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
19430 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
19440 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
19450 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
19460 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  or, .** [SQLITE_
19470 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61  SCHEMA] is now a
19480 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
19490 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  alling.** [sqlit
194a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
194b0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
194c0 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
194d0 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
194e0 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
194f0 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
19500 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
19510 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
19520 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
19530 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
19540 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e  EMA] return. {EN
19550 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  D}.** </li>.**.*
19560 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
19570 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
19580 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
19590 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
195a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
195b0 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  iled .** [error 
195c0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
195d0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
195e0 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79  . .** The legacy
195f0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
19600 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  at [sqlite3_step
19610 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
19620 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a  eturn a generic.
19630 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
19640 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e  ] result code an
19650 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
19660 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
19670 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  d call to.** [sq
19680 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
19690 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
196a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
196b0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
196c0 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  lem..** With the
196d0 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e   "v2" prepare in
196e0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
196f0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
19700 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
19710 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d  .** returned imm
19720 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
19730 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
19740 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
19750 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65  .** {F13011} The
19760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19770 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  e(db,zSql,...)] 
19780 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19790 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
197a0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
197b0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
197c0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
197d0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
197e0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
197f0 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  ter as UTF-8..**
19800 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65  .** {F13012} The
19810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19820 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  e16(db,zSql,...)
19830 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
19840 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
19850 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  re16_v2(db,zSql,
19860 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
19870 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
19880 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
19890 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
198a0 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31  rameter as UTF-1
198b0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
198c0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
198d0 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68  * {F13013} If th
198e0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
198f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
19900 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
19910 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
19920 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
19930 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73  variants is less
19940 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
19950 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
19960 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
19970 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
19980 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
19990 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
199a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20  .**.** {F13014} 
199b0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
199c0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
199d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
199e0 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
199f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
19a00 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
19a10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
19a20 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
19a30 65 73 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  es bytes.**     
19a40 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73       SQL text is
19a50 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
19a60 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20  .**.** {F13015} 
19a70 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  In [sqlite3_prep
19a80 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
19a90 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20  ,P,pzTail)] and 
19aa0 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
19ab0 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
19ac0 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20  zSql input text 
19ad0 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68  contains more th
19ae0 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65  an one SQL state
19af0 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
19b00 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e   and pzTail is n
19b10 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70  ot NULL, then *p
19b20 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
19b30 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a   point to the.**
19b40 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
19b50 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
19b60 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
19b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
19b80 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20  zSql..**        
19b90 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65    <todo>What doe
19ba0 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20  s *pzTail point 
19bb0 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f  to if there is o
19bc0 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74  ne statement?</t
19bd0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  odo>.**.** {F130
19be0 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  16} A successful
19bf0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19c00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
19c10 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e  zSql,N,ppStmt,..
19c20 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
19c30 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
19c40 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e  riants writes in
19c50 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69  to *ppStmt a poi
19c60 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
19c70 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
19c80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
19c90 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  r a pointer to N
19ca0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
19cb0 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
19cc0 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
19cd0 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f  han whitespace o
19ce0 72 20 63 6f 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a  r comments. .**.
19cf0 2a 2a 20 7b 46 31 33 30 31 39 7d 20 54 68 65 20  ** {F13019} The 
19d00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19d10 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
19d20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
19d30 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
19d40 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
19d50 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
19d60 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
19d70 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
19d80 0a 2a 2a 20 7b 46 31 33 30 32 31 7d 20 42 65 66  .** {F13021} Bef
19d90 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
19da0 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
19db0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
19dc0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
19dd0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
19de0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
19df0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
19e00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
19e10 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ]).**          i
19e20 74 20 66 69 72 73 74 20 73 65 74 73 20 2a 70 70  t first sets *pp
19e30 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
19e40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
19e50 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
19e60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
19e70 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
19e80 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
19e90 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
19ea0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
19eb0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
19ec0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
19ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
19ee0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
19ef0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
19f00 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
19f10 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
19f20 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
19f30 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
19f40 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
19f50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
19f60 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
19f70 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
19f80 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
19f90 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
19fa0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
19fb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
19fc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
19fd0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
19fe0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
19ff0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1a000 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1a010 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1a020 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1a030 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1a040 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1a050 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1a060 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1a070 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1a080 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1a090 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1a0a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1a0b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1a0c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1a0d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1a0e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a0f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a100 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a110 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1a120 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a130 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a140 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1a150 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a160 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a170 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a180 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a190 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a1a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a1b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a1c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a1d0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1a1e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a1f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a200 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a210 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a220 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1a230 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1a240 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1a250 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a260 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1a270 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1a280 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1a290 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1a2a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1a2b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1a2c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a2d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a2e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a2f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a300 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a310 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1a320 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a330 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a340 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a350 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1a360 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76  CAPIREF: Retriev
1a370 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
1a380 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a  L {F13100}.**.**
1a390 20 54 68 69 73 20 69 6e 74 65 72 65 66 61 63 65   This intereface
1a3a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a3b0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1a3c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1a3d0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1a3e0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1a3f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1a400 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49  tement]..**.** I
1a410 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1a420 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74 68 65   {F13101} If the
1a430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a440 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1a450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a460 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1a470 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a480 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1a490 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1a4a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1a4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a4c0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
1a4d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1a4e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
1a4f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
1a500 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a510 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a520 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
1a530 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1a540 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a550 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20  ng containing a 
1a560 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a  UTF-8 rendering.
1a570 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
1a580 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
1a590 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1a5a0 20 7b 46 31 33 31 30 32 7d 20 49 66 20 74 68 65   {F13102} If the
1a5b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a5c0 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1a5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a5e0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1a5f0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a600 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1a610 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1a620 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1a630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a640 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1a650 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1a660 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  re16()],.**     
1a670 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
1a680 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69  e3_sql()] functi
1a690 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  on returns a NUL
1a6a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1a6b0 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73 74   {F13103} The st
1a6c0 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
1a6d0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29   [sqlite3_sql(S)
1a6e0 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ] is valid until
1a6f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1a700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a710 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74  ment] S is delet
1a720 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1a730 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a  3_finalize(S)]..
1a740 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1a750 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1a760 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1a770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a780 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  :  Dynamically T
1a790 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1a7a0 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b  t  {F15000}.** K
1a7b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1a7c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a7d0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1a7e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1a7f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1a800 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1a810 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1a820 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1a830 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1a840 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1a850 61 62 61 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20  abase table..** 
1a860 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1a870 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74  mic typing for t
1a880 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1a890 72 65 73 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73  res.  .** Values
1a8a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1a8b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1a8c0 20 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e   can be.** be in
1a8d0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1a8e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1a8f0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1a900 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1a910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1a920 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1a930 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1a940 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1a950 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1a960 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1a970 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a980 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1a990 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1a9a0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1a9b0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1a9c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1a9d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1a9e0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1a9f0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1aa00 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1aa10 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 20 0a  ents specifies .
1aa20 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1aa30 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1aa40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1aa50 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1aa60 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1aa70 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1aa80 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1aa90 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1aaa0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1aab0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1aac0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1aad0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1aae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1aaf0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1ab00 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1ab10 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1ab20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1ab30 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1ab40 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1ab50 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1ab60 65 64 0a 2a 2a 20 28 77 69 74 68 20 53 51 4c 49  ed.** (with SQLI
1ab70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 20  TE_THREADSAFE=0 
1ab80 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1ab90 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1aba0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1abb0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1abc0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1abd0 77 65 65 6e 0a 2a 2a 20 70 72 6f 74 65 63 74 65  ween.** protecte
1abe0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1abf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1ac00 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1ac10 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 20   can be.** used 
1ac20 69 6e 74 65 72 63 68 61 6e 67 61 62 6c 65 2e 20  interchangable. 
1ac30 20 48 6f 77 65 76 65 72 2c 20 66 6f 72 20 6d 61   However, for ma
1ac40 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
1ac50 62 69 6c 69 74 79 20 69 74 0a 2a 2a 20 69 73 20  bility it.** is 
1ac60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1ac70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   applications ma
1ac80 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1ac90 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 62 65  on between.** be
1aca0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1acb0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20  and unprotected 
1acc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1acd0 6a 65 63 74 73 20 65 76 65 6e 20 69 66 0a 2a 2a  jects even if.**
1ace0 20 74 68 65 79 20 61 72 65 20 73 69 6e 67 6c 65   they are single
1acf0 20 74 68 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a   threaded..**.**
1ad00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1ad10 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1ad20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1ad30 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1ad40 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1ad50 69 6f 6e 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ion of applicati
1ad60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1ad70 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 70 72 6f  unctions are pro
1ad80 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
1ad90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ada0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1adb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1adc0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1add0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1ade0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1adf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ae00 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1ae10 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1ae20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1ae30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ae40 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20  bind_value()].  
1ae50 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  All other.** int
1ae60 65 72 66 61 63 65 73 20 74 68 61 74 20 75 73 65  erfaces that use
1ae70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 72   sqlite3_value r
1ae80 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1ae90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1aea0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1aeb0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1aec0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1aed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
1aee0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
1aef0 65 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30  ext Object {F160
1af00 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  01}.**.** The co
1af10 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1af20 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1af30 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1af40 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1af50 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1af60 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1af70 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1af80 65 78 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  ext.** object is
1af90 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1afa0 72 61 6d 65 74 65 72 20 74 6f 20 61 70 70 6c 69  rameter to appli
1afb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1afc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f  QL functions..*/
1afd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1afe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1aff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1b000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b010 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  :  Binding Value
1b020 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
1b030 61 74 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30  atements {F13500
1b040 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1b050 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1b060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1b070 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1b080 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20  ts.** variants, 
1b090 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1b0a0 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72  replace by a par
1b0b0 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a  ameter in one.**
1b0c0 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
1b0d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1b0e0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
1b0f0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
1b100 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
1b110 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
1b120 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
1b130 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
1b140 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
1b150 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
1b160 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56  er literal,.** V
1b170 56 56 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63  VV alpha-numeric
1b180 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e   parameter name.
1b190 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f  .** The values o
1b1a0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
1b1b0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1b1c0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1b1d0 6e 61 6d 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51  names".** or "SQ
1b1e0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1b1f0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1b200 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1b210 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1b220 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1b230 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1b240 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
1b250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1b260 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 0a  routines always.
1b270 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
1b280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1b290 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
1b2a0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
1b2b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b2c0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
1b2d0 61 6e 74 73 2e 20 54 68 65 20 73 65 63 6f 6e 64  ants. The second
1b2e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
1b2f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1b300 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
1b310 20 73 65 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72   set. The.** fir
1b320 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1b330 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
1b340 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e   When the same n
1b350 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  amed.** paramete
1b360 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1b370 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1b380 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1b390 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1b3a0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1b3b0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1b3c0 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20  occurrence. .** 
1b3d0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
1b3e0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
1b3f0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
1b400 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
1b410 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b420 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49  eter_name()] API
1b430 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1b440 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1b450 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1b460 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1b470 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1b480 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1b490 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1b4a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1b4b0 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
1b4c0 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
1b4d0 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
1b4e0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1b4f0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1b500 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1b510 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1b520 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b530 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f  * In those.** ro
1b540 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1b550 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1b560 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1b570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1b580 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70  ytes.** in the p
1b590 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1b5a0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1b5b0 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
1b5c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a  of <u>bytes</u>.
1b5d0 2a 2a 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  ** in the value,
1b5e0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1b5f0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20 0a  of characters. .
1b600 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
1b610 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1b620 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1b630 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1b640 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66   is.** number of
1b650 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1b660 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1b670 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1b680 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1b690 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1b6a0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1b6b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1b6c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1b6d0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1b6e0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1b6f0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1b700 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1b710 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1b720 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b730 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1b740 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1b750 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1b760 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1b770 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1b780 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1b790 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1b7a0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1b7b0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1b7c0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1b7d0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1b7e0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1b7f0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1b800 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1b810 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1b820 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1b830 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1b840 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1b850 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1b860 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1b870 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1b880 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1b890 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1b8a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1b8b0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1b8c0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1b8d0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1b8e0 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  d with zeros.  A
1b8f0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
1b900 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
1b910 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
1b920 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
1b930 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69  old it size) whi
1b940 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1b950 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1b960 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1b970 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1b980 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1b990 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
1b9a0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
1b9b0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
1b9c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1b9d0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1b9e0 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
1b9f0 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76  tines. A negativ
1ba00 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74  e.** value for t
1ba10 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1ba20 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1ba30 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1ba40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1ba50 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
1ba60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
1ba70 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
1ba80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
1ba90 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
1baa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1bab0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
1bac0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
1bad0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
1bae0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1baf0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1bb00 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1bb10 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
1bb20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1bb30 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1bb40 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
1bb50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1bb60 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1bb70 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
1bb80 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
1bb90 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1bba0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
1bbb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1bbc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1bbd0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1bbe0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
1bbf0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1bc00 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66  rned if malloc f
1bc10 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
1bc20 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
1bc30 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
1bc40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1bc50 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
1bc60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1bc70 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
1bc80 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
1bc90 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
1bca0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
1bcb0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
1bcc0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
1bcd0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
1bce0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
1bcf0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
1bd00 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
1bd10 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
1bd20 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
1bd30 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
1bd40 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
1bd50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
1bd60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1bd70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1bd80 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
1bd90 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
1bda0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
1bdb0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1bdc0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1bdd0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
1bde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bdf0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
1be00 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1be10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1be20 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
1be30 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1be40 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73   {F13506} The [s
1be50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1be60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
1be70 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69  ompiler] recogni
1be80 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zes.**          
1be90 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f  tokens of the fo
1bea0 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  rms "?", "?NNN",
1beb0 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c   "$VVV", ":VVV",
1bec0 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20   and "@VVV".**  
1bed0 20 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 70          as SQL p
1bee0 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65  arameters, where
1bef0 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75   NNN is any sequ
1bf00 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
1bf10 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
1bf20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 65  digits and where
1bf30 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75   VVV is any sequ
1bf40 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
1bf50 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ore .**         
1bf60 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68   alphanumeric ch
1bf70 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
1bf80 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
1bf90 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  owed by.**      
1bfa0 20 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e      a string con
1bfb0 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65  taining no space
1bfc0 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
1bfd0 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
1bfe0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30  es..**.** {F1350
1bff0 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
1c000 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
1c010 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
1c020 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d  ..**.** {F13512}
1c030 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
1c040 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
1c050 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
1c060 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
1c070 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
1c080 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
1c090 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
1c0a0 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
1c0b0 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
1c0c0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
1c0d0 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
1c0e0 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20  ** {F13515} The 
1c0f0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
1c100 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
1c110 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
1c120 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  NNN..**.** {F135
1c130 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
1c140 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
1c150 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
1c160 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
1c170 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
1c180 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
1c190 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
1c1a0 75 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20 73  urances of the s
1c1b0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1c1c0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e  parameter, or on
1c1d0 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20  e more than the 
1c1e0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76  largest index ov
1c1f0 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  er all.**       
1c200 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f     parameters to
1c210 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69   the left if thi
1c220 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f  s is the first o
1c230 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20  ccurrance.**    
1c240 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61        of this pa
1c250 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66  rameter, or 1 if
1c260 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66   this is the lef
1c270 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e  tmost parameter.
1c280 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20  .**.** {F13521} 
1c290 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1c2a0 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65  pare | SQL state
1c2b0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
1c2c0 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ail with.**     
1c2d0 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f       an [SQLITE_
1c2e0 52 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20  RANGE] error if 
1c2f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
1c300 53 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  SQL parameter.**
1c310 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73            is les
1c320 73 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61  s than 1 or grea
1c330 74 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f  ter than SQLITE_
1c340 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c350 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  BER..**.** {F135
1c360 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  24} Calls to [sq
1c370 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1c380 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1c390 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,V,...)].**   
1c3a0 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65         associate
1c3b0 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74   the value V wit
1c3c0 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  h all SQL parame
1c3d0 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a  ters having an.*
1c3e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78  *          index
1c3f0 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72   of N in the [pr
1c400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c410 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ] S..**.** {F135
1c420 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  27} Calls to [sq
1c430 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1c440 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1c450 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
1c460 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72       override pr
1c470 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74  ior calls with t
1c480 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f  he same values o
1c490 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a  f S and N..**.**
1c4a0 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e   {F13530} Bindin
1c4b0 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62  gs established b
1c4c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
1c4d0 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
1c4e0 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  ind(S,...)].**  
1c4f0 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20          persist 
1c500 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20  across calls to 
1c510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
1c520 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  )]..**.** {F1353
1c530 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  3} In calls to [
1c540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1c550 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
1c560 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c570 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1c580 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
1c590 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c5a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1c5b0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
1c5c0 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73  e binds the firs
1c5d0 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t L.**          
1c5e0 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f  bytes of the blo
1c5f0 62 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e  b or string poin
1c600 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65  ted to by V, whe
1c610 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n L.**          
1c620 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
1c630 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20  .**.** {F13536} 
1c640 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c650 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
1c660 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a  ,N,V,L,D)] or.**
1c670 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c680 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1c690 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
1c6a0 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65  e binds characte
1c6b0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  rs.**          f
1c6c0 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68  rom V through th
1c6d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
1c6e0 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73  racter when L is
1c6f0 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   negative..**.**
1c700 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c   {F13539} In cal
1c710 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1c720 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1c730 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1c740 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c750 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1c760 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1c770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c780 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1c790 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
1c7a0 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
1c7b0 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
1c7c0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51  LITE_STATIC], SQ
1c7d0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
1c7e0 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a  t the value V.**
1c7f0 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c            is hel
1c800 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61  d in static unma
1c810 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74  naged space that
1c820 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65   will not change
1c830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
1c840 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
1c850 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e   of the binding.
1c860 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20  .**.** {F13542} 
1c870 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c880 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
1c890 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
1c8a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c8b0 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
1c8c0 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
1c8d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c8e0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c8f0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
1c900 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a  s the special.**
1c910 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61            consta
1c920 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nt [SQLITE_TRANS
1c930 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69  IENT], the routi
1c940 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20  ne makes a .**  
1c950 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
1c960 63 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20  copy of V value 
1c970 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
1c980 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35  s..**.** {F13545
1c990 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1c9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1c9b0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1c9c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c9d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1c9e0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1c9f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ca00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1ca10 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1ca20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1ca30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
1ca40 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  unction, SQLite 
1ca50 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e  invokes that fun
1ca60 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79  ction to destroy
1ca70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ca80 20 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69   V value after i
1ca90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
1caa0 73 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65  sing the V value
1cab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d  ..**.** {F13548}
1cac0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1cad0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1cae0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68  lob(S,N,V,L)] th
1caf0 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a  e value bound.**
1cb00 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62            is a b
1cb10 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20  lob of L bytes, 
1cb20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
1cb30 20 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65   blob if L is ne
1cb40 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1cb50 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20  13551} In calls 
1cb60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1cb70 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74  _value(S,N,V)] t
1cb80 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61  he V argument ma
1cb90 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  y.**          be
1cba0 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65   either a [prote
1cbb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1cbc0 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e  ue] object or an
1cbd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e  .**          [un
1cbe0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1cbf0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
1cc00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cc10 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1cc20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cc30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1cc40 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cc50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cc60 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1cc70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1cc80 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1cc90 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1cca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1ccb0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1ccc0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1ccd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1cce0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1ccf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1cd00 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1cd10 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1cd20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1cd30 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1cd40 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1cd50 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1cd60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1cd70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1cd80 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1cd90 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1cda0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1cdb0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1cdc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1cdd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1cde0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1cdf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1ce00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1ce10 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1ce20 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1ce30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ce40 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1ce50 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31  L Parameters {F1
1ce60 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3600}.**.** This
1ce70 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1ce80 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1ce90 20 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70   number of SQL p
1cea0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20  arameters.** in 
1ceb0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
1cec0 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d  ment.  SQL param
1ced0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
1cee0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
1cef0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
1cf00 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
1cf10 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
1cf20 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f  e as.** place-ho
1cf30 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
1cf40 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
1cf50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1cf60 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
1cf70 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
1cf80 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
1cf90 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
1cfa0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
1cfb0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1cfc0 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74   largest paramet
1cfd0 65 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66  er..** For all f
1cfe0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
1cff0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
1d000 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75  espond to the nu
1d010 6d 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75  mber of.** uniqu
1d020 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
1d030 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
1d040 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65  the ?NNN are use
1d050 64 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20  d, there may.** 
1d060 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1d070 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ist..**.** See a
1d080 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1d090 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1d0a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1d0b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d0c0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1d0d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d0e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1d0f0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1d100 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1d110 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  13601} The [sqli
1d120 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d130 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  er_count(S)] int
1d140 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
1d150 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
1d160 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20  argest index of 
1d170 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
1d180 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  rs in the.**    
1d190 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1d1a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72  statement] S, or
1d1b0 20 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20   0 if S.**      
1d1c0 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20      contains no 
1d1d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
1d1e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1d1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1d200 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1d210 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d220 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1d230 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46  ost Parameter {F
1d240 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13620}.**.** Thi
1d250 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1d260 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1d270 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1d280 2d 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  -th.** SQL param
1d290 65 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61  eter in a [prepa
1d2a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1d2b0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
1d2c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
1d2d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1d2e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1d2f0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
1d300 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
1d310 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
1d320 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1d330 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
1d340 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
1d350 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
1d360 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
1d370 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
1d380 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
1d390 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
1d3a0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
1d3b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1d3c0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1d3d0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1d3e0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  r have no name..
1d3f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1d400 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1d410 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1d420 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  , not 0..**.** I
1d430 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73  f the value n is
1d440 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
1d450 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   if the n-th par
1d460 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
1d470 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
1d480 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
1d490 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1d4a0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
1d4b0 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  in the UTF-8 enc
1d4c0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
1d4d0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
1d4e0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
1d4f0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
1d500 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
1d510 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1d520 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1d530 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1d540 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1d560 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1d570 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1d580 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d590 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1d5a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d5b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1d5c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1d5d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1d5e0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
1d5f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d600 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1d610 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
1d620 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38           a UTF-8
1d630 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1d640 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
1d650 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  L parameter in.*
1d660 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
1d670 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d680 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e  S having index N
1d690 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1d6a0 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
1d6b0 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74  s no SQL paramet
1d6c0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
1d6d0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  or if the.**    
1d6e0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
1d6f0 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20  with index N is 
1d700 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  an anonymous par
1d710 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63  ameter "?"..*/.c
1d720 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1d730 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d740 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
1d750 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
1d760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
1d770 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
1d780 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
1d790 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a  ame {F13640}.**.
1d7a0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
1d7b0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1d7c0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
1d7d0 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
1d7e0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1d7f0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1d800 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1d810 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1d820 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1d830 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1d840 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
1d850 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
1d860 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
1d870 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
1d880 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
1d890 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1d8a0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1d8b0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1d8c0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1d8d0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1d8e0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1d8f0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1d900 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1d910 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1d920 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1d930 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1d940 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1d950 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d960 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1d970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1d980 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1d990 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1d9a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1d9b0 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
1d9c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d9d0 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
1d9e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1d9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1da00 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
1da10 61 6d 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61  ameter in [prepa
1da20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1da30 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
1da40 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
1da50 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
1da60 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
1da70 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
1da80 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
1da90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1daa0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1dab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1dac0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1dad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dae0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1daf0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1db00 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  red Statement {F
1db10 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e  13660}.**.** Con
1db20 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
1db30 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
1db40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1db50 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65  ] does not.** re
1db60 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  set the [sqlite3
1db70 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
1db80 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20  dings] on a .** 
1db90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1dba0 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20  ent].  Use this 
1dbb0 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65  routine to.** re
1dbc0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1dbd0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1dbe0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1dbf0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31  S:.**.** {F13661
1dc00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1dc10 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29  lear_bindings(S)
1dc20 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
1dc30 74 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  ts all.**       
1dc40 20 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72     SQL parameter
1dc50 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72   bindings in [pr
1dc60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dc70 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] S.**          
1dc80 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
1dc90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
1dca0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
1dcb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1dcc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1dcd0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
1dce0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1dcf0 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13710}.**.** Re
1dd00 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1dd10 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1dd20 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
1dd30 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  urned by the .**
1dd40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dd50 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
1dd60 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a  ine returns 0.**
1dd70 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1dd80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
1dd90 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
1dda0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a  rn data (for .**
1ddb0 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41   example an UPDA
1ddc0 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  TE)..**.** INVAR
1ddd0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1dde0 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
1ddf0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1de00 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
1de10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1de20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1de30 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
1de40 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
1de50 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ted by the.**   
1de60 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1de70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f   statement] S, o
1de80 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
1de90 74 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20  t generate.**   
1dea0 20 20 20 20 20 20 20 61 20 72 65 73 75 6c 74 20         a result 
1deb0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1dec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
1ded0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1dee0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1def0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
1df00 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
1df10 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a   Set {F13720}.**
1df20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1df30 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
1df40 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
1df50 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
1df60 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
1df70 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
1df80 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
1df90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1dfa0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
1dfb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
1dfc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1dfd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1dfe0 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  F8 string.** and
1dff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1e000 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
1e010 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1e020 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1e030 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  ** UTF16 string.
1e040 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1e050 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1e060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e070 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d  ent] that implem
1e080 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20  ents the SELECT 
1e090 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1e0a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1e0b0 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e  er is the column
1e0c0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1e0d0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
1e0e0 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  s.** number 0..*
1e0f0 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  *.** The returne
1e100 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
1e110 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1e120 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b  either the .** [
1e130 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e140 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1e150 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
1e160 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
1e170 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
1e180 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
1e190 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
1e1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e1b0 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
1e1c0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
1e1d0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
1e1e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
1e1f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
1e200 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
1e210 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
1e220 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
1e230 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
1e240 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
1e250 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1e260 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
1e270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
1e280 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
1e290 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
1e2a0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
1e2b0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
1e2c0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
1e2d0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
1e2e0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
1e2f0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
1e300 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
1e310 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
1e320 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
1e330 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
1e340 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
1e350 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
1e360 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
1e370 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1e380 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
1e390 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
1e3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1e3b0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
1e3c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1e3d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1e3e0 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1e3f0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
1e400 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74  mn (where 0 is t
1e410 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
1e420 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20  umn) for the.** 
1e430 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
1e440 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
1e450 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
1e460 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
1e470 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e480 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1e490 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75  ** {F13723} A su
1e4a0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1e4b0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
1e4c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e4d0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
1e4e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
1e4f0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
1e500 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1e510 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
1e520 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
1e530 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
1e540 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
1e550 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
1e560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e570 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
1e580 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1e590 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
1e5a0 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61  string in the na
1e5b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1e5c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20  .**.** {F13724} 
1e5d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1e5e0 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
1e5f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e600 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
1e610 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1e620 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
1e630 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
1e640 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
1e650 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
1e660 65 20 6d 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20  e memory memory 
1e670 74 6f 20 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f  to hold there no
1e680 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69  rmal return stri
1e690 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ngs..**.** {F137
1e6a0 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  25} If the N par
1e6b0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1e6c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e6d0 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
1e6e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1e6f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1e700 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1e710 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
1e720 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1e730 73 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  s returns a NULL
1e740 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a   pointer..** .**
1e750 20 7b 46 31 33 37 32 36 7d 20 54 68 65 20 73 74   {F13726} The st
1e760 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1e770 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1e780 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64  n_name(S,N)] and
1e790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1e7a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e7b0 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61  e16(S,N)] are va
1e7c0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1e7d0 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  xt.**          c
1e7e0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f  all to either ro
1e7f0 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73  utine with the s
1e800 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61  ame S and N para
1e810 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  meters.**       
1e820 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c     or until [sql
1e830 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
1e840 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  ] is called..**.
1e850 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e  ** {F13727} When
1e860 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1e870 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1e880 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e  tatement contain
1e890 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
1e8a0 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20   AS clause, the 
1e8b0 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c  name of that col
1e8c0 75 6d 6e 20 69 73 20 74 68 65 20 69 6e 64 65 6e  umn is the inden
1e8d0 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
1e8e0 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
1e8f0 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
1e900 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
1e910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e920 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1e930 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
1e940 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1e950 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
1e960 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e970 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
1e980 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
1e990 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
1e9a0 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d   Result {F13740}
1e9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1e9c0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
1e9d0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
1e9e0 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
1e9f0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
1ea00 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
1ea10 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
1ea20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1ea30 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
1ea40 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
1ea50 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
1ea60 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
1ea70 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
1ea80 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20  * either a UTF8 
1ea90 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  or UTF16 string.
1eaa0 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
1eab0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1eac0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1ead0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
1eae0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
1eaf0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
1eb00 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
1eb10 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
1eb20 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
1eb30 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
1eb40 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1eb50 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
1eb60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1eb70 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1eb80 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
1eb90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1eba0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1ebb0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1ebc0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1ebd0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1ebe0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1ebf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1ec00 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1ec10 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1ec20 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1ec30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1ec40 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1ec50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1ec60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1ec70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1ec80 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1ec90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1eca0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1ecb0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1ecc0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1ecd0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1ece0 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
1ecf0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
1ed00 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
1ed10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1ed20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
1ed30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1ed40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
1ed50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
1ed60 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
1ed70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
1ed80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
1ed90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
1eda0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
1edb0 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  urn NULL.  These
1edc0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
1edd0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
1ede0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
1edf0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
1ee00 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
1ee10 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
1ee20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  the .** name of 
1ee30 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
1ee40 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64  abase, table and
1ee50 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1ee60 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  ry result.** col
1ee70 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
1ee80 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
1ee90 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
1eea0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
1eeb0 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
1eec0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1eed0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1eee0 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
1eef0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
1ef00 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
1ef10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
1ef20 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
1ef30 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
1ef40 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
1ef50 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
1ef60 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
1ef70 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
1ef80 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1ef90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1efa0 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  U13751}.** If tw
1efb0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1efc0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1efd0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1efe0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1eff0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1f000 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1f010 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1f020 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1f030 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1f040 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1f050 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1f060 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20  ** {F13741} The 
1f070 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1f080 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c  database_name(S,
1f090 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1f0a0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1f0b0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1f0c0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1f0d0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
1f0e0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69  atabase from whi
1f0f0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f100 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f110 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f140 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f150 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f160 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f170 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f180 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f190 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f1a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f1b0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f1c0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f1d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f1e0 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {F13742} The [s
1f1f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f200 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
1f210 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1f220 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1f230 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1f240 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
1f250 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
1f260 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1f270 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
1f280 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
1f290 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1f2a0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1f2b0 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1f2c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1f2d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1f2e0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1f2f0 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1f300 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1f310 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1f320 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1f330 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1f340 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1f350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1f360 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1f370 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1f380 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {F13743} The [sq
1f390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1f3a0 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
1f3b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f3c0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1f3d0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1f3e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1f3f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1f400 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f410 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f420 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f430 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f440 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f450 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f460 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f470 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f480 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f490 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f4a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f4b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f4c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f4d0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f4e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f4f0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d      .** {F13744}
1f500 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f510 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
1f520 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
1f530 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1f540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f550 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
1f560 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
1f570 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1f580 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1f590 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
1f5a0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f5b0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f5c0 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f5e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f5f0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f600 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f610 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f620 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f630 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f640 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f650 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f660 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f670 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f690 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {F13745} The [s
1f6a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1f6b0 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
1f6c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1f6d0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1f6e0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
1f6f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1f700 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
1f710 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
1f720 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f730 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f740 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f770 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f780 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f790 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f7a0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f7b0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f7c0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f7d0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f7e0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f7f0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f810 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {F13746} The [s
1f820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1f830 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
1f840 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1f850 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1f860 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1f870 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1f880 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1f890 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f8a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
1f8b0 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
1f8c0 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1f8d0 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1f8e0 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1f8f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1f900 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1f910 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1f920 55 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e  ULL if the the N
1f930 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
1f940 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1f950 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
1f960 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
1f970 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1f980 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
1f990 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
1f9a0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
1f9b0 2a 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72  * {F13748} The r
1f9c0 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
1f9d0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
1f9e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f9f0 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
1fa00 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
1fa10 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
1fa20 20 20 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a      are valid.**
1fa30 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
1fa40 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
1fa50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1fa60 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
1fa70 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20     or until the 
1fa80 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e  encoding is chan
1fa90 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d  ged by another m
1faa0 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
1fab0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
1fac0 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ll for the same 
1fad0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fae0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  nt and column..*
1faf0 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
1fb00 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  :.**.** {U13751}
1fb10 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
1fb20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
1fb30 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
1fb40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1fb50 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1fb60 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1fb70 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1fb80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
1fb90 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
1fba0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
1fbb0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
1fbc0 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
1fbd0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1fbe0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1fbf0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
1fc00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1fc10 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1fc20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fc30 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fc40 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fc50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1fc60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1fc70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
1fc80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1fc90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
1fca0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1fcb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1fcc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1fcd0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
1fce0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1fcf0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fd00 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1fd10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fd20 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fd30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fd40 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
1fd50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1fd60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1fd70 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
1fd80 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
1fd90 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36  ry Result {F1376
1fda0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0}.**.** The fir
1fdb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1fdc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fdd0 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74  ement]. .** If t
1fde0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1fdf0 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
1fe00 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
1fe10 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a  column of the .*
1fe20 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
1fe30 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53 45  t set of that SE
1fe40 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20  LECT is a table 
1fe50 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
1fe60 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
1fe70 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
1fe80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
1fe90 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
1fea0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
1feb0 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
1fec0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
1fed0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
1fee0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
1fef0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
1ff00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
1ff10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
1ff20 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1ff30 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
1ff40 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e  -8 encoded.  {EN
1ff50 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  D} .** For examp
1ff60 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62  le, in the datab
1ff70 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1ff80 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1ff90 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1ffa0 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c  *.** And the fol
1ffb0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1ffc0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
1ffd0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
1ffe0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
1fff0 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * Then this rout
20000 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
20010 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
20020 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
20030 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63  cond.** result c
20040 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
20050 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
20060 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
20070 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
20080 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
20090 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
200a0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
200b0 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
200c0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
200d0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
200e0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
200f0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
20100 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
20110 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
20120 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
20130 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
20140 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
20150 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
20160 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
20170 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
20180 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
20190 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
201a0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
201b0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
201c0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
201d0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
201e0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
201f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
20200 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d  :.**.** {F13761}
20210 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
20220 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
20230 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
20240 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
20250 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
20260 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
20270 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
20280 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ning the.**     
20290 20 20 20 20 20 20 74 68 65 20 64 65 63 6c 61 72        the declar
202a0 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
202b0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
202c0 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
202d0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
202e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
202f0 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
20300 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20310 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
20320 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
20330 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
20340 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75  * {F13762}  A su
20350 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
20360 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20370 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
20380 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
20390 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
203a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
203b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
203c0 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  r string.**     
203d0 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67        containing
203e0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61   the declared da
203f0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  tatype of the ta
20400 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
20410 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20  appears.**      
20420 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20       as the Nth 
20430 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64  column (numbered
20440 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
20450 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
20460 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
20470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20480 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nt] S..**.** {F1
20490 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c  3763}  If N is l
204a0 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20  ess than 0 or N 
204b0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
204c0 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20  or equal to.**  
204d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d           the num
204e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
204f0 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
20500 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
20510 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20        or if the 
20520 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
20530 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
20540 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74   or subquery rat
20550 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
20560 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f   than a table co
20570 6c 75 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d  lumn or if a mem
20580 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
20590 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20  ailure.**       
205a0 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e      occurs durin
205b0 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65  g encoding conve
205c0 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20  rsions, then.** 
205d0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20            calls 
205e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
205f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
20600 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
20610 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
20620 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
20630 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  )] return NULL..
20640 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20660 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
20670 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20680 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20690 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
206a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
206b0 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
206c0 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
206d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
206e0 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13200}.**.**
206f0 20 41 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61   After an [prepa
20700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
20710 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
20720 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20   with a call.** 
20730 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  to either [sqlit
20740 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20750 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
20760 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
20770 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  to one of.** the
20780 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20790 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
207a0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
207b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
207c0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75  .** then this fu
207d0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63  nction must be c
207e0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
207f0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
20800 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74  ate the .** stat
20810 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
20820 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
20830 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
20840 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20850 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
20860 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
20870 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
20880 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
20890 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
208a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
208b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
208c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
208d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
208e0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
208f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
20900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20910 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
20920 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
20930 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
20940 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
20950 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
20960 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
20970 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
20980 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
20990 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
209a0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
209b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
209c0 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61  e lagacy interfa
209d0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
209e0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
209f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
20a00 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ], .** [SQLITE_D
20a10 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
20a20 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
20a30 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
20a40 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
20a50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
20a60 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
20a70 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  ther [SQLITE_OK 
20a80 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  | result code].*
20a90 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
20aa0 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
20ab0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
20ac0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
20ad0 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a  d as.** well..**
20ae0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
20af0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20b00 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
20b10 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
20b20 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
20b30 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
20b40 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
20b50 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
20b60 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d  tement is a COMM
20b70 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  IT.** or occurs 
20b80 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
20b90 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
20ba0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
20bb0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
20bc0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
20bd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
20be0 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f  t a COMMIT and o
20bf0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
20c00 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
20c10 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
20c20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
20c30 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
20c40 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
20c50 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
20c60 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
20c70 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
20c80 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
20c90 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
20ca0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
20cb0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
20cc0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
20cd0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
20ce0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
20cf0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
20d00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
20d10 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
20d20 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
20d30 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
20d40 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
20d50 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
20d60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
20d70 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
20d80 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
20d90 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  then .** [SQLITE
20da0 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65  _ROW] is returne
20db0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
20dc0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
20dd0 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72   ready.** for pr
20de0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20  ocessing by the 
20df0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
20e00 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
20e10 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
20e20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20e30 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63  int | column acc
20e40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
20e50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
20e60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
20e70 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
20e80 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
20e90 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49  ta..** .** [SQLI
20ea0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
20eb0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
20ec0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
20ed0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
20ee0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
20ef0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
20f00 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
20f10 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
20f20 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
20f30 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
20f40 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
20f50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
20f60 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
20f70 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
20f80 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
20f90 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
20fa0 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
20fb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
20fc0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
20fd0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
20fe0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
20ff0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
21000 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
21010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21020 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
21030 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21040 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
21050 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
21060 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
21070 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
21080 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
21090 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
210a0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
210b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
210c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
210d0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
210e0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
210f0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
21100 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
21110 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
21120 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
21130 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
21140 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
21150 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
21160 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
21170 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75   had .** previou
21180 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
21190 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
211a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
211b0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
211c0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
211d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
211e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
211f0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
21200 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
21210 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
21220 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
21230 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
21240 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
21250 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  /b>.** In the le
21260 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
21270 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
21280 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79  step() API alway
21290 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
212a0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a  ric error code,.
212b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
212c0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
212d0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
212e0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
212f0 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  ** and [SQLITE_M
21300 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
21310 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
21320 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
21330 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21340 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
21350 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20  find one of the 
21360 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72  specific.** [err
21370 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
21380 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
21390 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
213a0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
213b0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
213c0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
213d0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
213e0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
213f0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
21400 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
21410 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
21420 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
21430 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
21440 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21450 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21460 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
21470 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
21480 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
21490 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
214a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
214b0 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d  , then the .** m
214c0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
214d0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
214e0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
214f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
21500 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
21510 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
21520 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
21530 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
21540 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
21550 31 33 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70  13202}  If [prep
21560 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21570 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
21580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 75  .**           ru
21590 6e 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  n, then [sqlite3
215a0 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
215b0 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
215c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
215d0 20 20 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f          until to
215e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75   completion or u
215f0 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79  ntil it is ready
21600 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
21610 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
21620 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
21630 74 20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65  t set or an inte
21640 72 72 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d  rrupt or run-tim
21650 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
21660 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20  **.** {F15304}  
21670 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
21680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21690 20 63 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20   causes the .** 
216a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
216b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
216c0 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c   to run to compl
216d0 65 74 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20  etion,.**       
216e0 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
216f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21700 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
21710 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
21720 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21730 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
21740 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
21750 64 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  dy.**           
21760 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65  to return anothe
21770 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
21780 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
21790 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
217a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a   [SQLITE_ROW]..*
217b0 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49  *.** {F15308}  I
217c0 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
217d0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e  ite3_step(S)] en
217e0 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20  counters an.**  
217f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21800 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65  3_interrupt|inte
21810 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
21820 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
21830 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
21840 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 61 69  rns an approprai
21850 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
21860 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
21870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
21880 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
21890 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
218a0 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
218b0 20 7b 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {F15310}  If an
218c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
218d0 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f  upt|interrupt] o
218e0 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
218f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
21900 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61  curs during a ca
21910 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21920 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  tep(S)].**      
21930 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70       for a [prep
21940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21950 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  S created using.
21960 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67  **           leg
21970 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
21980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21990 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
219a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
219b0 61 72 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68  are16()] then th
219c0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
219d0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
219e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
219f0 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  RROR], [SQLITE_B
21a00 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  USY], or [SQLITE
21a10 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74  _MISUSE]..*/.int
21a20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
21a30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21a40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21a50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
21a60 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
21a70 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F13770}.**.** 
21a80 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
21a90 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
21aa0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
21ab0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21ac0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21ad0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37  TS:.**.** {F1377
21ae0 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
21af0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
21b00 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
21b10 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ns.**           
21b20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
21b30 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
21b40 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
21b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77  e.**           w
21b60 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
21b70 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
21b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
21b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
21ba0 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
21bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d  ..**.** {F13772}
21bc0 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
21bd0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
21be0 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
21bf0 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
21c00 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
21c10 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
21c20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21c30 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20  ] has been .**  
21c40 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20           called 
21c50 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
21c60 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a   statement] for.
21c70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
21c80 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63   first time sinc
21c90 65 20 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65  e it was [sqlite
21ca0 33 5f 70 72 65 70 61 72 65 7c 70 72 65 70 61 72  3_prepare|prepar
21cb0 65 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed].**          
21cc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
21cd0 65 74 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b  et|reset], the [
21ce0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
21cf0 6e 74 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  nt(S)].**       
21d00 20 20 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75      routine retu
21d10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
21d20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21d30 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21d40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21d50 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
21d60 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
21d70 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59   {F10265}.** KEY
21d80 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
21d90 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36  XT.**.** {F10266
21da0 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  }Every value in 
21db0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
21dc0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
21dd0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
21de0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
21df0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21e00 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
21e10 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
21e20 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
21e30 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
21e40 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
21e50 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
21e60 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
21e70 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
21e80 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
21e90 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
21ea0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
21eb0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
21ec0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
21ed0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
21ee0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
21ef0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
21f00 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
21f10 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
21f20 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
21f30 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
21f40 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
21f50 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
21f60 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
21f70 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
21f80 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
21f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
21fa0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
21fb0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
21fc0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
21fd0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
21fe0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
21ff0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
22000 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
22010 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
22020 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
22030 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
22040 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
22050 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
22060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22070 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
22080 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31  From A Query {F1
22090 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3800}.**.** Thes
220a0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
220b0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
220c0 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
220d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
220e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
220f0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a  formation about.
22100 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ** a single colu
22110 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
22120 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  t result row of 
22130 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
22140 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66  ry.** case the f
22150 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
22160 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22170 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
22180 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
22190 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
221a0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
221b0 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
221c0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
221d0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
221e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
221f0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
22200 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
22210 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
22220 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
22230 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
22240 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
22250 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
22260 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
22270 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
22280 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22290 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
222a0 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
222b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
222c0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
222d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
222e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
222f0 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
22300 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
22310 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
22320 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
22330 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
22340 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
22350 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
22360 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
22370 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
22380 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
22390 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
223a0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
223b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
223c0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
223d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
223e0 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
223f0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
22400 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
22410 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
22420 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
22430 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
22440 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22450 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
22460 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
22470 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
22480 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
22490 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
224a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
224b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
224c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
224d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
224e0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
224f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
22500 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
22510 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
22520 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
22530 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
22540 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
22550 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
22560 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
22570 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
22580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22590 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
225a0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
225b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
225c0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
225d0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
225e0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
225f0 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
22600 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
22610 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
22620 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
22630 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
22640 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
22650 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
22660 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
22670 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
22680 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22690 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
226a0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
226b0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
226c0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
226d0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
226e0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
226f0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
22700 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
22710 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
22720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22730 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
22740 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
22750 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22760 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
22770 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
22780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22790 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
227a0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
227b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
227c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
227d0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
227e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
227f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
22800 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
22810 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
22820 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
22830 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
22840 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
22850 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
22860 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
22870 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22880 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
22890 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
228a0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
228b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
228c0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
228d0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
228e0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
228f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22900 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
22910 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
22920 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
22930 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
22940 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
22950 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
22960 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
22970 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
22980 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
22990 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
229a0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
229b0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
229c0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
229d0 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
229e0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
229f0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
22a00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
22a10 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
22a20 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
22a30 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
22a40 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
22a50 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
22a60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
22a70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22a80 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
22a90 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
22aa0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
22ab0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
22ac0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
22ad0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
22ae0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
22af0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
22b00 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69   blob is an arbi
22b10 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
22b20 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
22b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22b40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22b50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22b60 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
22b70 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
22b80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
22b90 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
22ba0 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
22bb0 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
22bc0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
22bd0 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54  of UTF-8.  .** T
22be0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
22bf0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
22c00 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
22c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
22c20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
22c30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
22c40 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
22c50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22c60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22c70 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
22c80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22c90 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
22ca0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
22cb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
22cc0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
22cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
22ce0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
22cf0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
22d00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22d10 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
22d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
22d30 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
22d40 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
22d50 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
22d60 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
22d70 74 69 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b  tines like .** [
22d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
22d90 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
22da0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
22db0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22dc0 62 79 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65  bytes()],.** the
22dd0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
22de0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
22df0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22e00 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
22e10 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
22e20 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
22e30 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
22e40 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
22e50 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
22e60 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
22e70 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
22e80 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
22e90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
22ea0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
22eb0 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20  nally to do the 
22ec0 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75  conversion.** au
22ed0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
22ee0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
22ef0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
22f00 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a  nversions that.*
22f10 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  * are applied:.*
22f20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
22f30 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
22f40 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
22f50 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
22f60 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
22f70 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
22f80 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
22f90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
22fa0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
22fb0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
22fc0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
22fd0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
22fe0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
22ff0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
23000 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
23010 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23020 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
23030 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
23040 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
23050 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
23060 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
23070 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
23080 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
23090 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
230a0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
230b0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
230c0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
230d0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
230e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
230f0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
23100 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
23110 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
23120 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23130 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20  td> Same as for 
23140 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
23150 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
23160 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23170 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
23180 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
23190 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
231a0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
231b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
231c0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
231d0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
231e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
231f0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23200 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
23210 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
23220 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
23230 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23240 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
23250 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
23260 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
23270 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
23280 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
23290 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
232a0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
232b0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
232c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
232d0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
232e0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
232f0 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
23300 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
23310 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
23320 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
23330 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
23340 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
23350 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
23360 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
23370 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
23380 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
23390 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
233a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
233b0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
233c0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
233d0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
233e0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
233f0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
23400 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
23410 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
23420 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
23430 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
23440 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74  ** on equavalent
23450 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
23460 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
23470 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
23480 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
23490 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
234a0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
234b0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
234c0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
234d0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
234e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
234f0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
23500 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
23510 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
23520 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
23530 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
23540 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
23550 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
23560 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
23570 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23580 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
23590 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63  ated. .** Type c
235a0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
235b0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
235c0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
235d0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
235e0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
235f0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70  * <ul>.** <li><p
23600 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
23610 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
23620 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
23630 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20  umn_text() .**  
23640 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74          or sqlit
23650 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23660 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
23670 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
23680 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20   might.**       
23690 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
236a0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
236b0 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  g.</p></li>.**.*
236c0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
236d0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
236e0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
236f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23700 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
23710 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
23720 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23730 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
23740 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
23750 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
23760 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36         to UTF-16
23770 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
23780 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
23790 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
237a0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
237b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
237c0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
237d0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
237e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
237f0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
23800 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
23810 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
23820 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e     to UTF-8.</p>
23830 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
23840 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
23850 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
23860 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
23870 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
23880 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
23890 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
238a0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
238b0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
238c0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
238d0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
238e0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
238f0 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23900 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23910 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
23920 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
23930 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
23940 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
23950 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
23960 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69  ut sometime it i
23970 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
23980 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
23990 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
239a0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
239b0 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ted.  .**.** The
239c0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
239d0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
239e0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
239f0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
23a00 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
23a10 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
23a20 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a  ys:.**.**  <ul>.
23a30 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
23a40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
23a50 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
23a60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23a70 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
23a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23a90 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
23aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23ab0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
23ac0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
23ad0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
23ae0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
23af0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23b00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a  </li>.**  </ul>.
23b10 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
23b20 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
23b30 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
23b40 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c  lumn_text(), sql
23b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23b60 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  (),.** or sqlite
23b70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23b80 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
23b90 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
23ba0 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20   the desired.** 
23bb0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
23bc0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
23bd0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71  mn_bytes() or sq
23be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23bf0 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e  es16() to.** fin
23c00 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
23c10 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
23c20 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71  t mix call to sq
23c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23c40 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  t() or.** sqlite
23c50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
23c60 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
23c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23c80 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20  es16().  And do 
23c90 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73  not.** mix calls
23ca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
23cb0 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68  mn_text16() with
23cc0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23cd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
23cf0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
23d00 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
23d10 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
23d20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
23d30 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
23d40 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
23d50 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
23d60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
23d70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
23d80 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
23d90 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73  d.  The memory s
23da0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
23db0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
23dc0 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20   blobs is freed 
23dd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
23de0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
23df0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
23e00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
23e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23e20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
23e30 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
23e40 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c  c. into .** [sql
23e50 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
23e60 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
23e70 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
23e80 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
23e90 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
23ea0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
23eb0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
23ec0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
23ed0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
23ee0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
23ef0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
23f00 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
23f10 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
23f20 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
23f30 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
23f40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
23f50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
23f60 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
23f70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
23f80 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  M]..**.** INVARI
23f90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
23fa0 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
23fb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
23fc0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
23fd0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
23fe0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
23ff0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
24000 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
24010 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
24020 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
24030 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
24040 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68  to a blob and th
24050 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
24060 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
24070 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
24080 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
24090 46 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c  F13806} The [sql
240a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
240b0 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  s(S,N)] interfac
240c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
240d0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
240e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
240f0 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20   blob or string 
24100 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
24110 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
24120 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
24130 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
24140 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
24150 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
24160 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
24170 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
24180 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
24190 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
241a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
241b0 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  text(S,N)]..**.*
241c0 2a 20 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b  * {F13809} The [
241d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
241e0 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74  ytes16(S,N)] int
241f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24200 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
24210 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
24220 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
24230 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
24240 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
24250 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
24260 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
24270 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
24280 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
24290 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
242a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
242b0 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e  mn_text16(S,N)].
242c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20  .**.** {F13812} 
242d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
242e0 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d  umn_double(S,N)]
242f0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
24300 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
24310 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
24320 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
24330 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
24340 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
24350 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24360 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
24370 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
24380 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
24390 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
243a0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
243b0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
243c0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
243d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
243e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
243f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
24400 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
24410 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
24420 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
24430 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
24440 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24450 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
24460 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
24470 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
24480 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
24490 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
244a0 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
244b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  er..**.** {F1381
244c0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
244d0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e  column_int64(S,N
244e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
244f0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
24500 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
24510 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24520 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
24530 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
24540 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
24550 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
24560 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
24570 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
24580 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
24590 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
245a0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
245b0 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71  {F13821} The [sq
245c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
245d0 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  t(S,N)] interfac
245e0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
245f0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24600 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
24610 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24620 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
24630 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24650 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
24660 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a  rminated UTF-8 .
24670 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
24680 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
24690 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
246a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
246b0 46 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c  F13824} The [sql
246c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
246d0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
246e0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
246f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24700 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24710 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24720 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24750 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
24760 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
24770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
24780 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
24790 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
247a0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
247b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
247c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
247d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
247e0 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  3827} The [sqlit
247f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53  e3_column_type(S
24800 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24810 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
24820 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54     one of [SQLIT
24830 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_NULL], [SQLITE
24840 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
24850 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20  TE_FLOAT],.**   
24860 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
24870 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  EXT], or [SQLITE
24880 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
24890 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20  riate for.**    
248a0 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f        the Nth co
248b0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
248c0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
248d0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
248e0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
248f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24900 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d  ..**.** {F13830}
24910 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24920 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
24930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24940 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
24950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
24960 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24970 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24980 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
24990 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
249a0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
249b0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
249c0 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
249d0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
249e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
249f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24a00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24a10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24a20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24a40 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
24a50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24a60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24a70 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
24a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24a90 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
24aa0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
24ab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24ac0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
24ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24ae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24af0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
24b00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
24b10 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
24b20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24b30 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
24b40 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
24b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24b60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24b70 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
24b80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
24b90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
24ba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24bb0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
24bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24be0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
24bf0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
24c00 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
24c10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24c20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
24c30 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
24c40 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24c50 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33  ment Object {F13
24c60 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  300}.**.** The s
24c70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24c80 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
24c90 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
24ca0 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
24cb0 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68  tatement]. If th
24cc0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  e statement was.
24cd0 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63  ** executed succ
24ce0 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74  essfully, or not
24cf0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
24d00 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b  , then SQLITE_OK
24d10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24d20 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
24d30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
24d40 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a  ailed then an .*
24d50 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
24d60 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
24d70 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
24d80 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  turned. .**.** T
24d90 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
24da0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
24db0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
24dc0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
24dd0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24de0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
24df0 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
24e00 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  ine has not .** 
24e10 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
24e20 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
24e30 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
24e40 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
24e50 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
24e60 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74   error or an int
24e70 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73  errupt.  (See [s
24e80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
24e90 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70  ()].) .** Incomp
24ea0 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
24eb0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
24ec0 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
24ed0 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a   cancelled,  .**
24ee0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
24ef0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
24f00 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72   and the .** [er
24f10 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
24f20 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
24f30 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
24f40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
24f50 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20  ** {F11302} The 
24f60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24f70 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
24f80 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20  destroys the.** 
24f90 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
24fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24fb0 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c  and releases all
24fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
24fd0 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73  ory and file res
24fe0 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74  ources held by t
24ff0 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  hat object..**.*
25000 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68  * {F11304} If th
25010 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
25020 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25030 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
25040 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25050 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25060 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65   S returned an e
25070 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
25080 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
25090 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74  finalize(S)] ret
250a0 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65  urns that same e
250b0 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
250c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
250d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
250e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
250f0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
25100 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25110 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a  Object {F13330}.
25120 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25130 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
25140 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
25150 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65  reset a .** [pre
25160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25170 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b   object..** back
25180 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
25190 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
251a0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
251b0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
251c0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
251d0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
251e0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
251f0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
25200 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
25210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
25220 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
25230 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
25240 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
25250 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
25260 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
25270 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32  s..**.** {F11332
25280 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
25290 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
252a0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
252b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
252c0 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
252d0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
252e0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
252f0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ogram..**.** {F1
25300 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73  1334} If the mos
25310 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
25320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25330 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20  )] for .**      
25340 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
25350 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
25360 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
25370 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
25380 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
25390 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
253a0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
253b0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
253c0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
253d0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
253e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
253f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
25400 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36  ]..**.** {F11336
25410 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
25420 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25430 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
25440 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
25450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25460 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
25470 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
25480 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25490 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
254a0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
254b0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
254c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38  ]..**.** {F11338
254d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
254e0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
254f0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
25500 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
25510 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
25520 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25530 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
25540 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25550 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
25560 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
25570 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25580 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25590 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
255a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
255b0 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a  tions {F16100}.*
255c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
255d0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
255e0 6f 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20  outines} .**.** 
255f0 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69  These two functi
25600 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
25610 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66  y known as.** "f
25620 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
25630 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65 20   routines") are 
25640 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
25650 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25660 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f  regates.** or to
25670 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
25680 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69  havior of existi
25690 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
256a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
256b0 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e   The.** differen
256c0 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20  ce only between 
256d0 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20  the two is that 
256e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
256f0 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d  eter, the.** nam
25700 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
25710 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  ) function or ag
25720 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f  gregate, is enco
25730 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72  ded in UTF-8 for
25740 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
25750 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
25760 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c  d UTF-16 for sql
25770 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25780 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
25790 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
257a0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
257b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
257c0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
257d0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
257e0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49   to be added.  I
257f0 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72  f a single.** pr
25800 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
25810 74 68 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61  than one [databa
25820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
25830 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
25840 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
25850 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
25860 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65  ndividually to e
25870 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
25880 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
25890 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
258a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
258b0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
258c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
258d0 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69  ted.** or redefi
258e0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67  ned..** The leng
258f0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
25900 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
25910 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
25920 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72  e of the .** zer
25930 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
25940 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
25950 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
25960 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
25970 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
25980 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
25990 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
259a0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
259b0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
259c0 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f  lt in an SQLITE_
259d0 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a  ERROR error..**.
259e0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
259f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75  ameter is the nu
25a00 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25a10 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
25a20 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
25a30 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
25a40 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
25a50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
25a60 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
25a70 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
25a80 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
25a90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
25aa0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
25ab0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25ac0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
25ad0 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b  ifies what .** [
25ae0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
25af0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
25b00 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
25b10 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
25b20 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
25b30 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
25b40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
25b50 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
25b60 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
25b70 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
25b80 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
25b90 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
25ba0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
25bb0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
25bc0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
25bd0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
25be0 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
25bf0 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
25c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25c10 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
25c20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25c30 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
25c40 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
25c50 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
25c60 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
25c70 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
25c80 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
25c90 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
25ca0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
25cb0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
25cc0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
25cd0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
25ce0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
25cf0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
25d00 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
25d10 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
25d20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
25d30 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
25d40 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
25d50 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
25d60 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  t.** text encodi
25d70 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
25d80 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
25d90 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ment should be.*
25da0 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  * [SQLITE_ANY]..
25db0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
25dc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
25dd0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
25de0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
25df0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
25e00 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
25e10 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
25e20 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a  s pointer using.
25e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ** [sqlite3_user
25e40 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
25e50 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
25e60 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
25e70 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
25e80 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
25e90 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
25ea0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
25eb0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25ec0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
25ed0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72  L.** function or
25ee0 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
25ef0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
25f00 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
25f10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a  plementation of.
25f20 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c  ** the xFunc cal
25f30 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
25f40 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
25f50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
25f60 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  e xStep.** and x
25f70 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  Final parameters
25f80 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
25f90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
25fa0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
25fb0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74  tation.** of xSt
25fc0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ep and xFinal an
25fd0 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
25fe0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
25ff0 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a  c. To delete an.
26000 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  ** existing SQL 
26010 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
26020 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
26030 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
26040 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
26050 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ack..**.** It is
26060 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
26070 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
26080 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
26090 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
260a0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
260b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
260c0 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
260d0 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
260e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
260f0 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66 65   differing perfe
26100 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
26110 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
26120 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
26130 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
26140 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
26150 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
26160 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
26170 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
26180 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
26190 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20  .**.** {F16103} 
261a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
261b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
261c0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
261d0 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
261e0 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
261f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26200 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
26210 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
26220 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
26230 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
26240 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
26250 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20  gument as.**    
26260 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
26270 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
26280 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
26290 6e 73 74 65 61 64 20 6f 66 20 61 73 20 61 0a 2a  nstead of as a.*
262a0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
262b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
262c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d  ..**.** {F16106}
262d0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
262e0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  vocation of.**  
262f0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
26300 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26310 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
26320 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
26330 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  isters.**       
26340 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
26350 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
26360 73 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s in [database c
26370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
26380 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f           used to
26390 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
263a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
263b0 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d  d X with N param
263c0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
263d0 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70    and having a p
263e0 65 72 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  erferred text en
263f0 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a  coding of E..**.
26400 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20 73 75  ** {F16109} A su
26410 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
26420 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26430 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26440 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
26450 20 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73          replaces
26460 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e   the P, F, S, an
26470 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  d L values from 
26480 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
26490 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
264a0 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20   the same D, X, 
264b0 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e  N, and E values.
264c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20  .**.** {F16112} 
264d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
264e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
264f0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
26500 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20   fails with.**  
26510 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
26520 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
26530 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53  _ERROR] if the S
26540 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
26550 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   X is.**        
26560 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35    longer than 25
26570 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76  5 bytes exclusiv
26580 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65  e of the zero te
26590 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
265a0 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65 72 20  {F16118} Either 
265b0 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61  F must be NULL a
265c0 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
265d0 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  on-NULL or else 
265e0 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  F.**          is
265f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20   non-NULL and S 
26600 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20  and L are NULL, 
26610 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20  otherwise.**    
26620 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
26630 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26640 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
26650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
26660 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _ERROR]..**.** {
26670 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  F16121} The [sql
26680 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26690 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  tion(D,...)] int
266a0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
266b0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
266c0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
266d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20  SQLITE_BUSY] if 
266e0 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65  there exist [pre
266f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
26700 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
26710 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
26720 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26730 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
26740 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20 5b 73   {F16124} The [s
26750 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26760 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
26770 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
26780 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
26790 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
267a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
267b0 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72  OR] if parameter
267c0 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74   N (specifying t
267d0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
267e0 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e        of argumen
267f0 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
26800 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67  nction being reg
26810 69 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73  istered) is less
26820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
26830 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
26840 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20  than 127..**.** 
26850 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20  {F16127} When N 
26860 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
26870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
26880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
26890 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
268a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
268b0 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73  causes callbacks
268c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66   to be invoked f
268d0 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
268e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
268f0 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65  named X when the
26900 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
26910 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
26920 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  function is.**  
26930 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20          exactly 
26940 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30  N..**.** {F16130
26950 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20  } When N is -1, 
26960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
26970 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
26980 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
26990 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
269a0 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
269b0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
269c0 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
269d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
269e0 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20  amed X with any 
269f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
26a00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  nts..**.** {F161
26a10 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  33} When calls t
26a20 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
26a30 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
26a40 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
26a50 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
26a60 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
26a70 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
26a80 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20  function X.**   
26a90 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20         and when 
26aa0 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  one implementati
26ab0 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20  on has N>=0 and 
26ac0 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d  the other has N=
26ad0 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  (-1).**         
26ae0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
26af0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ion with a non-z
26b00 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72  ero N is preferr
26b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33  ed..**.** {F1613
26b20 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  6} When calls to
26b30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26b40 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26b50 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  E,...)].**      
26b60 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74      specify mult
26b70 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
26b80 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
26b90 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
26ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26bb0 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20   same number of 
26bc0 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20  arguments N but 
26bd0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a  with different.*
26be0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
26bf0 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65  ings E, then the
26c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26c10 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20  where E matches 
26c20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26c30 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
26c40 67 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a  g is preferred..
26c50 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46  **.** {F16139} F
26c60 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  or an aggregate 
26c70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65  SQL function cre
26c80 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
26c90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26ca0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26cb0 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29  D,X,N,E,P,0,S,L)
26cc0 5d 20 74 68 65 20 66 69 6e 69 61 6c 69 7a 65 72  ] the finializer
26cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
26ce0 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77  ction L will alw
26cf0 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  ays be invoked e
26d00 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74  xactly once if t
26d10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  he.**          s
26d20 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69  tep function S i
26d30 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  s called one or 
26d40 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a  more times..**.*
26d50 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20  * {F16142} When 
26d60 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65  SQLite invokes e
26d70 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20  ither the xFunc 
26d80 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f  or xStep functio
26d90 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  n of.**         
26da0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
26db0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26dc0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
26dd0 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20  e created.**    
26de0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
26df0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26e00 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
26e10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26e20 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
26e30 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61     then the arra
26e40 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  y of [sqlite3_va
26e50 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73  lue] objects pas
26e60 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20  sed as the.**   
26e70 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72         third par
26e80 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 79  ameter are alway
26e90 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  s [protected sql
26ea0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26eb0 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  cts..*/.int sqli
26ec0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26ed0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
26ee0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
26ef0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26f00 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26f10 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26f20 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26f30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
26f40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26f60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
26f70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26f80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26f90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26fa0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26fb0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
26fc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26fd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
26fe0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
26ff0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
27000 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
27010 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
27020 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
27030 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
27040 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
27050 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
27060 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
27070 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
27080 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
27090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
270a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
270b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
270c0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
270d0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
270e0 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d  codings {F10267}
270f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
27100 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
27110 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
27120 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
27130 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
27140 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
27150 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
27160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27170 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
27180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27190 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
271a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
271b0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
271c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
271d0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
271e0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
271f0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
27200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
27210 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
27220 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
27230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
27240 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
27250 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
27260 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
27270 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27280 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
27290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73  ** CAPI3REF: Obs
272a0 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a  olete Functions.
272b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
272c0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f  tions are all no
272d0 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20  w obsolete.  In 
272e0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
272f0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
27300 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
27310 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65  h older code, we
27320 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70   continue to sup
27330 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75  port.** these fu
27340 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65  nctions.  Howeve
27350 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65  r, new developme
27360 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75  nt projects shou
27370 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
27380 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
27390 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
273a0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
273b0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
273c0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
273d0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
273e0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
273f0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
27400 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
27410 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
27420 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
27440 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
27450 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
27460 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
27470 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
27480 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
27490 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
274a0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
274b0 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
274c0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
274d0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
274e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
274f0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
27500 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
27510 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
27520 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
27530 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
27540 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
27550 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
27560 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F15100}.**.** 
27570 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
27580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
27590 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
275a0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
275b0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
275c0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
275d0 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
275e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
275f0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
27600 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
27610 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
27620 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
27630 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
27640 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
27650 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
27660 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
27670 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
27680 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27690 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
276a0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
276b0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
276c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
276d0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
276e0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
276f0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
27700 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
27710 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
27720 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
27730 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27740 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27750 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
27760 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27770 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
27780 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
27790 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
277a0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
277b0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
277c0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
277d0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
277e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
277f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
27800 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
27810 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
27820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27830 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
27840 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
27850 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
27860 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
27870 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27880 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
27890 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
278a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
278b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
278c0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
278d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
278e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
278f0 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  umn_blob | sqlit
27900 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74  e3_column_* rout
27910 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61  ines] except tha
27920 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  t .** these rout
27930 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
27940 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
27950 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27960 65 63 74 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69  ect pointer.** i
27970 6e 73 74 65 61 64 20 6f 66 20 61 6e 20 5b 73 71  nstead of an [sq
27980 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
27990 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
279a0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
279b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
279c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
279d0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
279e0 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20 73  tracts a UTF16 s
279f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
27a00 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
27a10 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
27a20 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
27a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27a40 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
27a50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27a60 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
27a70 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31 36  ** extract UTF16
27a80 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
27a90 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
27aa0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
27ab0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
27ac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
27ad0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
27ae0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
27af0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
27b00 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
27b10 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
27b20 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
27b30 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
27b40 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
27b50 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
27b60 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
27b70 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
27b80 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
27b90 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
27ba0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
27bb0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
27bc0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20  her.** words if 
27bd0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
27be0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
27bf0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
27c00 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
27c10 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20  ersion is done. 
27c20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
27c30 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
27c40 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54    The .** [SQLIT
27c50 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
27c60 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
27c70 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
27c80 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  ed..**.** Please
27c90 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
27ca0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
27cb0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
27cc0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ointer that.** i
27cd0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
27ce0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27cf0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27d00 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
27d10 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
27d20 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
27d30 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
27d40 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
27d50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
27d60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27d70 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
27d80 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
27d90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27da0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
27db0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27dc0 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  xt16()].  .**.**
27dd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27de0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27df0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27e00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
27e10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
27e20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27e30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27e40 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a  rameters..**.**.
27e50 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
27e60 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54 68  *.** {F15103} Th
27e70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27e80 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
27e90 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
27ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
27eb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27ec0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
27ed0 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20  into a blob and 
27ee0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a  then returns a.*
27ef0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
27f00 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
27f10 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
27f20 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {F15106} The [s
27f30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27f40 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
27f50 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
27f60 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
27f70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27f80 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28  blob or string (
27f90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
27fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
27fb0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
27fc0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
27fd0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
27fe0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27ff0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28000 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
28010 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
28020 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
28040 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
28050 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
28060 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
28070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28080 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
28090 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
280a0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
280b0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
280c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
280d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
280e0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
280f0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
28100 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
28110 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
28120 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28130 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
28140 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
28150 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28160 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
28170 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28180 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
28190 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20  ** {F15112} The 
281a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
281b0 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
281c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
281d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
281e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
281f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
28200 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
28210 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
28220 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
28230 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
28240 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
28250 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {F15115} The [sq
28260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
28270 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
28280 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28290 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
282a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
282b0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
282c0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
282d0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
282e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
282f0 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
28300 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
28310 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d  ..**.** {F15118}
28320 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28330 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
28340 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28360 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
28370 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28380 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
28390 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
283a0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
283b0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
283c0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
283d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20  .**.** {F15121} 
283e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
283f0 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
28400 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28410 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
28420 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28430 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28440 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
28450 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a  rminated UTF-8 .
28460 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
28470 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
28480 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28490 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
284a0 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F15124} The [sql
284b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
284c0 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
284d0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
284e0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
284f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28500 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28510 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28520 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
28530 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
28540 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
28550 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
28560 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
28570 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28580 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28590 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54  **.** {F15127} T
285a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
285b0 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
285c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
285d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
285e0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
285f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28600 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
28610 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
28620 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
28630 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
28640 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
28650 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
28660 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28670 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
28680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d  ..**.** {F15130}
28690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
286a0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
286b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
286c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
286d0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
286e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
286f0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
28700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
28710 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
28720 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
28730 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
28740 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
28750 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
28760 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
28770 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
28780 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
28790 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
287a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
287b0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
287c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
287d0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
287e0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
287f0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
28800 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
28810 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
28820 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
28830 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
28840 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
28850 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
28860 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20  .**.** {F15136} 
28870 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28880 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
28890 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
288a0 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
288b0 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
288c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
288d0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
288e0 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
288f0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
28900 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
28910 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
28920 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
28930 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
28940 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
28950 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
28960 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
28970 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
28980 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
28990 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
289a0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
289b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
289c0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
289d0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
289e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
289f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28a00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28a10 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
28a20 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
28a30 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
28a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28a50 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
28a60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28a70 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
28a80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
28a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
28aa0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
28ab0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
28ac0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
28ad0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
28ae0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
28af0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
28b00 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
28b10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28b20 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
28b30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28b40 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
28b50 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
28b60 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
28b70 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
28b80 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
28b90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
28ba0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
28bb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28bc0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
28bd0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
28be0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28bf0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28c10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28c20 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
28c30 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28c40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
28c50 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
28c60 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
28c70 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
28c80 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
28c90 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36  ion Context {F16
28ca0 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  210}.**.** The i
28cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28cc0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
28cd0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
28ce0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
28cf0 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
28d00 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
28d10 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a   their state.  .
28d20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
28d30 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
28d40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28d50 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
28d60 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
28d70 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
28d80 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
28d90 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
28da0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73   memory.** zeros
28db0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
28dc0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28dd0 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e  ter to it..** On
28de0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
28df0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
28e00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28e10 65 5f 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66  e_context().** f
28e20 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
28e30 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
28e40 6e 64 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62  ndex, the same b
28e50 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
28e60 64 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  d..** The implem
28e70 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
28e80 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
28e90 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e 65   use the returne
28ea0 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
28eb0 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
28ec0 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  ** SQLite automa
28ed0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
28ee0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66  e allocated buff
28ef0 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  er when the aggr
28f00 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63  egate.** query c
28f10 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
28f20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28f30 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
28f40 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  copy of the .** 
28f50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
28f60 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
28f70 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
28f80 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
28f90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
28fa0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
28fb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
28fc0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
28fd0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
28fe0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
28ff0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
29000 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
29010 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
29020 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
29030 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
29040 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
29050 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
29060 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20  6211} The first 
29070 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
29080 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29090 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
290a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
290b0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
290c0 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65  ance of an aggre
290d0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66  gate function (f
290e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
290f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
29100 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51  ext C) causes SQ
29110 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  Lite to allocati
29120 6f 6e 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  on N bytes of me
29130 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20  mory,.**        
29140 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f    zero that memo
29150 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ry, and return a
29160 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29170 61 6c 6c 6f 63 61 74 69 6f 6e 65 64 0a 2a 2a 20  allocationed.** 
29180 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e           memory.
29190 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20  .**.** {F16213} 
291a0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
291b0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
291c0 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20  urs during.**   
291d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
291e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
291f0 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65  t(C,N)] then the
29200 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
29210 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  s 0..**.** {F162
29220 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73  15} Second and s
29230 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
29240 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20  tions of.**     
29250 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
29260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29270 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61  C,N)] for the sa
29280 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  me context point
29290 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  er C.**         
292a0 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61   ignore the N pa
292b0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
292c0 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
292d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
292e0 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65       block of me
292f0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
29300 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63   the first invoc
29310 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ation..**.** {F1
29320 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79  6217} The memory
29330 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73   allocated by [s
29340 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29350 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69  _context(C,N)] i
29360 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  s.**          au
29370 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
29380 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61  d on the next ca
29390 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
293a0 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  eset()].**      
293b0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
293c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20  finalize()] for 
293d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
293e0 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e  atement] contain
293f0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
29400 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
29410 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
29420 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  d with context C
29430 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
29440 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29450 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
29460 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
29470 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
29480 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
29490 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  or Functions {F1
294a0 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6240}.**.** The 
294b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
294c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
294d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
294e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
294f0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
29500 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
29510 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
29520 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  er).** of the th
29530 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
29540 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
29550 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29560 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29570 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
29580 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
29590 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
295a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
295b0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
295c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
295d0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
295e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
295f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
29600 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
29610 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29620 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
29630 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
29640 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34  TS:.**.** {F1624
29650 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
29660 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e  user_data(C)] in
29670 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29680 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
29690 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e            P poin
296a0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
296b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
296c0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
296d0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
296e0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
296f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
29700 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
29710 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
29720 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
29730 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
29740 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
29750 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20   with .**       
29760 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74     [sqlite3_cont
29770 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  ext] C..*/.void 
29780 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
29790 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
297a0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
297b0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
297c0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
297d0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30  unctions {F16250
297e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
297f0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
29800 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
29810 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
29820 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
29830 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
29840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29850 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
29860 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  er).** of the th
29870 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
29880 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
29890 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
298a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
298b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
298c0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
298d0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
298e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
298f0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
29900 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29910 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65  .** {F16253} The
29920 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
29930 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20  t_db_handle(C)] 
29940 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29950 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
29960 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f  **          D po
29970 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
29980 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29990 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
299a0 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
299b0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
299c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
299d0 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
299e0 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
299f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
29a00 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
29a10 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
29a20 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20  ed with .**     
29a30 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
29a40 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c  ntext] C..*/.sql
29a50 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
29a60 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
29a70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29a90 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
29aa0 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31 36  iliary Data {F16
29ab0 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  270}.**.** The f
29ac0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
29ad0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
29ae0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
29af0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
29b00 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
29b10 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
29b20 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
29b30 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
29b40 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
29b50 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
29b60 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
29b70 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
29b80 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
29b90 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
29ba0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
29bb0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
29bc0 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70  ta-data may be p
29bd0 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
29be0 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
29bf0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
29c00 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
29c10 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
29c20 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
29c30 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
29c40 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
29c50 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
29c60 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
29c70 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73  .** meta-data as
29c80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
29c90 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
29ca0 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
29cb0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
29cc0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
29cd0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
29ce0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
29cf0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
29d00 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
29d10 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
29d20 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
29d30 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
29d40 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
29d50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
29d60 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
29d70 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
29d80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29d90 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
29da0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29db0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29dc0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
29dd0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
29de0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
29df0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
29e00 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
29e10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
29e20 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
29e30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29e40 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20  ction..** If no 
29e50 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65  meta-data has be
29e60 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65 74  en ever been set
29e70 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20   for the Nth.** 
29e80 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29e90 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
29ea0 74 68 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e  the coorespondin
29eb0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
29ec0 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e  eter.** has chan
29ed0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
29ee0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
29ef0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
29f00 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72  t_auxdata().** r
29f10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
29f20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
29f30 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
29f40 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
29f50 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d   saves the meta-
29f60 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
29f70 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
29f80 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
29f90 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65  eta-data for the
29fa0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
29fb0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
29fc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29fd0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
29fe0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
29ff0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a000 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2a010 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2a020 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2a030 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a  en destroyed. .*
2a040 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
2a050 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
2a060 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2a070 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74  ructor .** funct
2a080 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
2a090 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2a0a0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
2a0b0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
2a0c0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e  e meta-data when
2a0d0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2a0e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2a0f0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
2a100 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
2a110 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
2a120 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
2a130 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
2a140 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
2a150 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
2a160 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
2a170 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a  p meta-data on.*
2a180 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72 20  * any parameter 
2a190 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2a1a0 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68  at any time.  Th
2a1b0 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
2a1c0 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65 20  .** is that the 
2a1d0 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
2a1e0 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
2a1f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
2a200 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a  .** dropped..**.
2a210 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20  ** In practice, 
2a220 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72 65  meta-data is pre
2a230 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2a240 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2a250 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2a260 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2a270 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2a280 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2a290 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2a2a0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69  ues and SQL vari
2a2b0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ables..**.** The
2a2c0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2a2d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2a2e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2a2f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2a300 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2a310 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2a320 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a330 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73   {F16272} The [s
2a340 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a350 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ta(C,N)] interfa
2a360 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a370 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
2a380 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   to metadata ass
2a390 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2a3a0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2a3b0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2a3c0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
2a3d0 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20  hose context is 
2a3e0 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  C, or NULL if th
2a3f0 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
2a400 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ta associated.**
2a410 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
2a420 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  hat parameter..*
2a430 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68  *.** {F16274} Th
2a440 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2a450 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2a460 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67   interface assig
2a470 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ns a metadata.**
2a480 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2a490 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70  r P to the Nth p
2a4a0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2a4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  SQL function wit
2a4c0 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  h context.**    
2a4d0 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b        C..**.** {
2a4e0 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77  F16276} SQLite w
2a4f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2a500 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
2a510 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2a520 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
2a530 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61  hich is the meta
2a540 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66  data pointer P f
2a550 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
2a560 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
2a570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a580 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68  ata(C,N,P,D)] wh
2a590 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  en SQLite ceases
2a5a0 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20   to hold.**     
2a5b0 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74       the metadat
2a5c0 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37  a..**.** {F16277
2a5d0 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20  } SQLite ceases 
2a5e0 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61  to hold metadata
2a5f0 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63   for an SQL func
2a600 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
2a610 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
2a620 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
2a630 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  t parameter chan
2a640 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ges..**.** {F162
2a650 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  78} When [sqlite
2a660 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2a670 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b  N,P,D)] is invok
2a680 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74  ed, the destruct
2a690 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
2a6a0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79  s called for any
2a6b0 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20   prior metadata 
2a6c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a6d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2a6e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  n.**          co
2a6f0 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61  ntext C and para
2a700 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  meter N..**.** {
2a710 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77  F16279} SQLite w
2a720 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63  ill call destruc
2a730 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74  tors for any met
2a740 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64  adata it is hold
2a750 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2a760 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2a770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a780 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68  ent] S when eith
2a790 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
2a7a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a7b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2a7c0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
2a7d0 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  lled..*/.void *s
2a7e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a7f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2a800 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
2a810 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
2a820 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2a830 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
2a840 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
2a850 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
2a860 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
2a870 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
2a880 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
2a890 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30  Behavior {F10280
2a8a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  }.**.** These ar
2a8b0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2a8c0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
2a8d0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
2a8e0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
2a8f0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
2a900 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2a910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a920 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
2a930 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2a940 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2a950 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2a960 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2a970 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2a980 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2a990 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2a9a0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2a9b0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2a9c0 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
2a9d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2a9e0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2a9f0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2aa00 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2aa10 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2aa20 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2aa30 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2aa40 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2aa50 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2aa60 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2aa70 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2aa80 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2aa90 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2aaa0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2aab0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2aac0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2aad0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2aae0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2aaf0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2ab00 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2ab10 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2ab20 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2ab30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2ab40 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2ab50 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2ab60 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2ab70 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2ab80 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2ab90 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2aba0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2abb0 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34  L Function {F164
2abc0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
2abd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2abe0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
2abf0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2ac00 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
2ac10 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
2ac20 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2ac30 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
2ac40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ac50 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2ac60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ac70 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
2ac80 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2ac90 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2aca0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
2acb0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
2acc0 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  e the .** [sqlit
2acd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2ace0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66  qlite3_bind_*] f
2acf0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
2ad00 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69  ns used.** to bi
2ad10 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
2ad20 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
2ad30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ad40 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
2ad50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2ad60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2ad70 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75  ite3_bind_* docu
2ad80 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a  mentation] for.*
2ad90 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
2ada0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2adb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2adc0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2add0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2ade0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2adf0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2ae00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ae10 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2ae20 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2ae30 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2ae40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ae50 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2ae60 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2ae70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2ae80 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a  ird parameter. .
2ae90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2aea0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
2aeb0 20 69 6e 65 72 66 61 63 65 73 20 73 65 74 20 74   inerfaces set t
2aec0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2aed0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2aee0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2aef0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
2af00 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
2af10 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
2af20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
2af30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
2af40 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
2af50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2af60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2af70 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
2af80 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2af90 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2afa0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2afb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2afc0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2afd0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2afe0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2aff0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2b000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b010 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2b020 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2b030 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
2b040 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
2b050 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
2b060 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
2b070 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
2b080 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  n..** SQLite use
2b090 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2b0a0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2b0b0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2b0c0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2b0d0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2b0e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b0f0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2b100 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2b110 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74   message.  SQLit
2b120 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2b130 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2b140 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2b150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b160 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20 53 51  or() as UTF8. SQ
2b170 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2b180 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2b190 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2b1a0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2b1b0 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  TF16 in native.*
2b1c0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
2b1d0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2b1e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b1f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2b200 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b210 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2b220 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2b230 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2b240 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2b250 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2b260 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2b270 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2b280 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
2b290 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b2a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b2b0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
2b2c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b2d0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
2b2e0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2b2f0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
2b300 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
2b310 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
2b320 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2b330 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
2b340 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
2b350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b360 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2b370 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b380 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2b390 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76  make a copy priv
2b3a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2b3b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2b3c0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2b3d0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2b3e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2b3f0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2b400 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2b410 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2b420 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2b430 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
2b440 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b450 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2b460 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2b470 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2b480 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2b490 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2b4a0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2b4b0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
2b4c0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2b4d0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2b4e0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
2b4f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2b500 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2b510 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2b520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b530 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2b540 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2b550 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2b560 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b570 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
2b580 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2b590 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74  s SQLite.** to t
2b5a0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e  hrow an error in
2b5b0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2b5c0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
2b5d0 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20  s to long.** to 
2b5e0 72 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20  represent.  The 
2b5f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2b600 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2b610 0a 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74  .** causes SQLit
2b620 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  e to throw an ex
2b630 63 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69  ception indicati
2b640 6e 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a  ng that the a.**
2b650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2b660 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
2b670 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b680 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2b690 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2b6a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2b6b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b6c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b6d0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2b6e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2b6f0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2b700 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2b710 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
2b720 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2b730 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2b740 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2b750 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2b760 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b770 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b780 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2b790 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2b7a0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2b7b0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2b7c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b7d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2b7e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2b7f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2b800 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2b810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b820 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2b830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b840 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2b850 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2b860 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73  _text16(), .** s
2b870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2b880 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2b890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2b8a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2b8b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2b8c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2b8d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b8e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b8f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2b900 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2b910 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2b920 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2b930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2b940 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2b950 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2b960 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2b970 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53  spectively..** S
2b980 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2b990 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2b9a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b9b0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2b9c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2b9d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b9e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2b9f0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  s..** If the 3rd
2ba00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2ba10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ba20 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2ba30 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2ba40 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2ba50 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2ba60 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2ba70 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75  ameter .** throu
2ba80 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2ba90 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2baa0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2bab0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2bac0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2bad0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2bae0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2baf0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2bb00 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2bb10 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2bb20 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2bb30 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2bb40 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2bb50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bb60 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2bb70 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
2bb80 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2bb90 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2bba0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2bbb0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2bbc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bbd0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2bbe0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2bbf0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2bc00 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2bc10 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2bc20 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2bc30 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e  blob result when
2bc40 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2bc50 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2bc60 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2bc70 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2bc80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2bc90 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2bca0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2bcb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2bcc0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2bcd0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2bce0 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53  TATIC, then.** S
2bcf0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2bd00 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  at the text or b
2bd10 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f  lob result is co
2bd20 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
2bd30 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70  .** does not cop
2bd40 79 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63  y the space or c
2bd50 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2bd60 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2bd70 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2bd80 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
2bd90 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2bda0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2bdb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2bdc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2bdd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bde0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2bdf0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2be00 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2be10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2be20 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2be30 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2be40 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2be50 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2be60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2be70 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2be80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2be90 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2bea0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2beb0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2bec0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bed0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bee0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2bef0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2bf00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2bf10 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2bf20 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2bf30 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
2bf40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2bf50 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2bf60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2bf70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2bf80 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2bf90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2bfa0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
2bfc0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
2bfd0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
2bfe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bff0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
2c000 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2c010 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
2c020 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c030 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2c040 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2c050 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2c060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c070 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2c080 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2c090 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2c0a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2c0b0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2c0c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2c0d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2c0e0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2c0f0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2c100 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2c110 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65  ead .** than the
2c120 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
2c130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c140 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c150 20 74 68 61 74 20 72 65 63 69 65 76 65 64 0a 2a   that recieved.*
2c160 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
2c170 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
2c180 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2c190 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c1a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c1b0 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65  .** {F16403} The
2c1c0 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
2c1d0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
2c1e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
2c1f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2c200 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
2c210 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2c220 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2c230 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2c240 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2c250 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2c260 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62  n C to be a blob
2c270 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73   that is N bytes
2c280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
2c290 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20  length and with 
2c2a0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20  content pointed 
2c2b0 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  to by V..**.** {
2c2c0 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c  F16409} The [sql
2c2d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2c2e0 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
2c2f0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2c300 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2c310 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2c320 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2c330 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2c340 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
2c350 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16412} The [sqli
2c360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c370 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
2c380 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2c390 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2c3a0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
2c3b0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
2c3c0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
2c3d0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
2c3e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
2c3f0 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65  OR] and a UTF8 e
2c400 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70  rror message cop
2c410 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
2c420 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c430 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65   first zero byte
2c440 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2c450 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20  s are read if N 
2c460 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
2c470 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20  ** {F16415} The 
2c480 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c490 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20  error16(C,V,N)] 
2c4a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c4b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
2c4c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
2c4d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c4e0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c4f0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2c500 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2c510 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
2c520 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79   UTF16 native by
2c530 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
2c540 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
2c550 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
2c560 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2c570 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c580 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2c590 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
2c5a0 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
2c5b0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2c5c0 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  F16418} The [sql
2c5d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c5e0 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
2c5f0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2c600 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
2c610 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
2c620 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
2c630 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
2c640 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
2c650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2c660 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
2c670 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c680 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2c690 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68  *.** {F16421} Th
2c6a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c6b0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
2c6c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2c6d0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
2c6e0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
2c6f0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2c700 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
2c710 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
2c720 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
2c730 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
2c740 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
2c750 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
2c760 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34  e..**.** {F16424
2c770 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c780 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2c790 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
2c7a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c7b0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c7c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
2c7d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2c7e0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2c7f0 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
2c800 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
2c810 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2c820 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
2c830 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68  *.** {F16427} Th
2c840 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c850 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
2c860 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2c880 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2c890 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2c8a0 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
2c8b0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
2c8c0 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {F16430} The [s
2c8d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2c8e0 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
2c8f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2c900 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2c910 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2c920 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2c930 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
2c940 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
2c950 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  F16433} The [sql
2c960 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
2c970 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
2c980 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2c990 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2c9a0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c9b0 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
2c9c0 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65  .** {F16436} The
2c9d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c9e0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
2c9f0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2ca00 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ca10 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2ca20 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2ca30 62 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69  be the UTF8 stri
2ca40 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  ng.**          V
2ca50 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2ca60 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
2ca70 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
2ca80 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
2ca90 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
2caa0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2cab0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39  e..**.** {F16439
2cac0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2cad0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
2cae0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2caf0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2cb00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2cb10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2cb20 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2cb30 46 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  F16 native byte 
2cb40 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
2cb50 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
2cb60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2cb70 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
2cb80 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
2cb90 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2cba0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
2cbb0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2cbc0 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20  ** {F16442} The 
2cbd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cbe0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2cbf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2cc00 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cc10 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2cc20 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cc30 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2cc40 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
2cc50 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
2cc60 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2cc70 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20  zero if N is.** 
2cc80 20 20 20 20 20 20 20 20 20 69 73 20 6e 65 67 61           is nega
2cc90 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2cca0 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
2ccb0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2ccc0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2ccd0 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
2cce0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2ccf0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2cd00 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2cd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2cd20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2cd30 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2cd40 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65  e UTF16 little-e
2cd50 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2cd60 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
2cd70 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2cd80 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
2cd90 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
2cda0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2cdb0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
2cdc0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2cdd0 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20  ** {F16448} The 
2cde0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cdf0 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65  value(C,V)] inte
2ce00 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2ce10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2ce20 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2ce30 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b  nction C to be [
2ce40 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ce50 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20  te3_value].**   
2ce60 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e         object V.
2ce70 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20  .**.** {F16451} 
2ce80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2ce90 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
2cea0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2ceb0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cec0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2ced0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cee0 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20  to be an N-byte 
2cef0 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f  blob of all zero
2cf00 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34  s..**.** {F16454
2cf10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2cf20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61  esult_error()] a
2cf30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2cf40 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a  lt_error16()].**
2cf50 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2cf60 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79  aces make a copy
2cf70 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20   of their error 
2cf80 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
2cf90 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  before.**       
2cfa0 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a     returning..**
2cfb0 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20  .** {F16457} If 
2cfc0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
2cfd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2cfe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2cff0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
2d000 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d010 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
2d020 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
2d030 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d040 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2d050 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d060 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d070 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
2d080 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d0a0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
2d0b0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53   the constant [S
2d0c0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a  QLITE_STATIC].**
2d0d0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e            then n
2d0e0 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  o destructor is 
2d0f0 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ever called on t
2d100 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64  he pointer V and
2d110 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
2d120 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74      assumes that
2d130 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e   V is immutable.
2d140 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20  .**.** {F16460} 
2d150 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
2d160 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
2d170 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d180 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
2d190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d1a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d1b0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
2d1c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d1d0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
2d1e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d1f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d200 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
2d210 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2d220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d230 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
2d240 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
2d250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2d260 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
2d270 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
2d280 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ces makes a copy
2d290 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2d2a0 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56      content of V
2d2b0 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65   and retains the
2d2c0 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   copy..**.** {F1
2d2d0 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64  6463} If the D d
2d2e0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
2d2f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d300 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
2d310 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2d320 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d330 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
2d340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
2d350 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
2d360 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2d370 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d380 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
2d390 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
2d3a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2d3b0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
2d3c0 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76  ,N,D)] is some v
2d3d0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
2d3e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2d3f0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
2d400 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53  E_STATIC] and [S
2d410 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2d420 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20   then .**       
2d430 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69     SQLite will i
2d440 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2d450 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73  ctor D with V as
2d460 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
2d470 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
2d480 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2d490 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76  hed with the V v
2d4a0 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alue..*/.void sq
2d4b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2d4c0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2d4d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2d4e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2d4f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2d500 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2d510 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2d520 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
2d530 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d540 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
2d550 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2d560 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
2d570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d580 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
2d590 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d5a0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
2d5b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d5c0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
2d5d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d5e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d5f0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
2d600 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d610 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2d620 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
2d630 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
2d640 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2d650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2d660 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2d670 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2d680 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2d690 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
2d6a0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
2d6b0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
2d6c0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2d6d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d6e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d6f0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
2d700 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d710 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
2d720 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d730 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d740 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
2d750 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d760 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d770 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d780 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d790 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2d7a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d7b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d7c0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2d7d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d7e0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
2d7f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d800 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d810 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2d820 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d830 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
2d840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2d850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d860 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d870 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
2d880 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d890 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2d8a0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
2d8b0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
2d8c0 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a  uences {F16600}.
2d8d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2d8e0 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
2d8f0 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
2d900 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
2d910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2d920 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66  *] handle specif
2d930 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2d940 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a   argument. .**.*
2d950 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
2d960 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2d970 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2d980 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2d990 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2d9a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d9b0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2d9c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d9d0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2d9e0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2d9f0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2da00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2da10 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
2da20 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
2da30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
2da40 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2da50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2da60 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2da70 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
2da80 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
2da90 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2daa0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2dab0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2dac0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
2dad0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
2dae0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
2daf0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
2db00 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
2db10 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
2db20 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
2db30 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2db40 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
2db50 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
2db60 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
2db70 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
2db80 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
2db90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2dba0 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
2dbb0 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
2dbc0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
2dbd0 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
2dbe0 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
2dbf0 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
2dc00 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
2dc10 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
2dc20 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
2dc30 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
2dc40 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
2dc50 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
2dc60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2dc70 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
2dc80 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
2dc90 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
2dca0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
2dcb0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
2dcc0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
2dcd0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
2dce0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
2dcf0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
2dd00 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
2dd10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
2dd20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2dd30 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2dd40 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
2dd50 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
2dd60 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61  .** the fourth a
2dd70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2dd80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dd90 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ion() or.** sqli
2dda0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2ddb0 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20  tion16() as its 
2ddc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
2ddd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
2dde0 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
2ddf0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
2de00 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
2de10 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
2de20 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
2de30 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
2de40 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
2de50 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
2de60 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
2de70 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
2de80 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
2de90 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
2dea0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2deb0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
2dec0 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61  red. {END} The a
2ded0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2dee0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75  ed collation rou
2def0 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  tine should.** r
2df00 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
2df10 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
2df20 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   if.** the first
2df30 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
2df40 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
2df50 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2df60 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74  the second.** st
2df70 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
2df80 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
2df90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2dfa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2dfb0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2dfc0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2dfd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2dfe0 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20   excapt that it 
2dff0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
2e000 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2e010 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
2e020 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
2e030 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
2e040 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
2e050 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2e060 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
2e070 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
2e080 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
2e090 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
2e0a0 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
2e0b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
2e0c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e0d0 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
2e0e0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
2e0f0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
2e100 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
2e110 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
2e120 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
2e130 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
2e140 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
2e150 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
2e160 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
2e170 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
2e180 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
2e190 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2e1a0 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20  *.** {F16603} A 
2e1b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2e1c0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
2e1d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2e1e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2e1f0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
2e200 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
2e210 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
2e220 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
2e230 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e240 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
2e250 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
2e260 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
2e270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e280 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
2e290 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
2e2a0 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
2e2b0 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ng E..**.** {F16
2e2c0 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
2e2d0 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
2e2e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
2e2f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2e300 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e310 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2e320 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
2e330 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
2e340 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
2e350 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
2e360 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
2e370 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
2e380 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
2e390 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
2e3a0 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
2e3b0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cters..**.** {F1
2e3c0 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
2e3d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2e3e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e3f0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2e400 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
2e410 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
2e420 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
2e430 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
2e440 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
2e450 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
2e460 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
2e470 46 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74  F16609} The dest
2e480 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
2e490 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e4a0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2e4b0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
2e4c0 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
2e4d0 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
2e4e0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
2e4f0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
2e500 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
2e510 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
2e520 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
2e530 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20  *.** {F16612} A 
2e540 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2e550 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
2e560 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
2e570 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ded..**.** {F166
2e580 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
2e590 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
2e5a0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
2e5b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2e5d0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
2e5e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
2e5f0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54  **.** {F16618} T
2e600 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
2e610 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e620 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2e630 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
2e640 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
2e650 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
2e660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e670 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
2e680 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
2e690 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
2e6a0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2e6b0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
2e6c0 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63  .** {F16621} A c
2e6d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e6e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e6f0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
2e700 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
2e710 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
2e720 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
2e730 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e740 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
2e750 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2e760 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
2e770 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
2e780 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ctor..**.** {F16
2e790 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
2e7a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e7b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e7c0 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
2e7d0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
2e7e0 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
2e7f0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
2e800 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
2e810 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
2e820 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
2e830 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e840 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74  ction] B on text
2e850 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20   values that.** 
2e860 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65           use the
2e870 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
2e880 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a  nce name X..**.*
2e890 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b  * {F16627} The [
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 31 36 28 42 2c 58 2c 45  ollation16(B,X,E
2e8c0 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65  ,P,F)] works the
2e8d0 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
2e8e0 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72    as [sqlite3_cr
2e8f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
2e900 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70  ,X,E,P,F)] excep
2e910 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  t that the.**   
2e920 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e         collation
2e930 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72   name X is under
2e940 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20  stood as UTF-16 
2e950 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
2e960 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
2e970 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
2e980 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30  8..**.** {F16630
2e990 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  } When multiple 
2e9a0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e9b0 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
2e9c0 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a  le for the same.
2e9d0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
2e9e0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
2e9f0 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74  SQLite chooses t
2ea00 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78  he one whose tex
2ea10 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20  t encoding.**   
2ea20 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20         requires 
2ea30 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2ea40 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66   of conversion f
2ea50 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a  rom the default.
2ea60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
2ea70 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2ea80 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e   database..*/.in
2ea90 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2eaa0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
2eab0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2eac0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2ead0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2eae0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2eaf0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2eb00 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2eb10 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2eb20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2eb30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2eb40 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
2eb50 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2eb60 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2eb70 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2eb80 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2eb90 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2eba0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2ebb0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
2ebc0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2ebd0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2ebe0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ebf0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
2ec00 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2ec10 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2ec20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2ec30 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2ec40 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2ec50 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2ec60 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2ec70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec80 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2ec90 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37   Callbacks {F167
2eca0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00}.**.** To avo
2ecb0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
2ecc0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
2ecd0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
2ece0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
2ecf0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
2ed00 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
2ed10 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2ed20 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
2ed30 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  h the.** databas
2ed40 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63  e handle to be c
2ed50 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
2ed60 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
2ed70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2ed80 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a  s.** required..*
2ed90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
2eda0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2edb0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2edc0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2edd0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2ede0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2edf0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2ee00 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2ee10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2ee20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2ee30 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31  ed in UTF-8. {F1
2ee40 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
2ee50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ee60 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74  d16() is used, t
2ee70 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20  he names.** are 
2ee80 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
2ee90 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
2eea0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41  ve byte order. A
2eeb0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a   call to either.
2eec0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  ** function repl
2eed0 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
2eee0 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
2eef0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
2ef00 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2ef10 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ef20 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2ef30 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2ef40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2ef50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ef60 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2ef70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2ef80 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2ef90 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2efa0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2efb0 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20  base.** handle. 
2efc0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2efd0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2efe0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2eff0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2f000 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2f010 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2f020 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65  g the most.** de
2f030 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2f040 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
2f050 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2f060 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65  required..** The
2f070 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f080 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2f090 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
2f0a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2f0b0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
2f0c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2f0d0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2f0e0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2f0f0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2f100 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f110 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2f120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2f130 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2f140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2f150 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2f160 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
2f170 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2f180 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66  6702} A successf
2f190 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2f1a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f1b0 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20  eded(D,P,F)].** 
2f1c0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2f1d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f1e0 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20  eeded16(D,P,F)] 
2f1f0 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20  causes.**       
2f200 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
2f210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
2f220 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63  o invoke callbac
2f230 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a  k F with first.*
2f240 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
2f250 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20  eter P whenever 
2f260 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61  it needs a compa
2f270 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66  rison function f
2f280 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  or a.**         
2f290 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
2f2a0 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  nce that it does
2f2b0 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e   not know about.
2f2c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20  .**.** {F16704} 
2f2d0 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20  Each successful 
2f2e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f2f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f300 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  d()] or.**      
2f310 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
2f320 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2f330 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
2f340 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74   callback regist
2f350 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
2f360 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2f370 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f380 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  n] by prior call
2f390 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20  s to either.**  
2f3a0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f3b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36  e..**.** {F16706
2f3c0 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  } The name of th
2f3d0 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c  e requested coll
2f3e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  ating function p
2f3f0 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  assed in the.** 
2f400 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72           4th par
2f410 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
2f420 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46  llback is in UTF
2f430 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  -8 if the callba
2f440 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ck.**          w
2f450 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  as registered us
2f460 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
2f470 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2f480 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2f490 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61   is in UTF-16 na
2f4a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2f4b0 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
2f4c0 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
2f4d0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2f4e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2f4f0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
2f500 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73  .**.** .*/.int s
2f510 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f520 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2f530 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2f540 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2f550 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2f560 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2f570 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2f580 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f590 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2f5a0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2f5b0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2f5c0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2f5d0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2f5e0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2f5f0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
2f600 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
2f610 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
2f620 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
2f630 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
2f640 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
2f650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2f660 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2f670 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2f680 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2f690 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2f6a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2f6b0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
2f6c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2f6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f6e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2f6f0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2f700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2f710 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2f720 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
2f730 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
2f740 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
2f750 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
2f760 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
2f770 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
2f780 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
2f790 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
2f7a0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
2f7b0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
2f7c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
2f7d0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
2f7e0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2f7f0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2f800 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2f810 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2f820 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2f830 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2f840 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
2f850 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2f860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f870 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2f880 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2f890 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2f8a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2f8b0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
2f8c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f8d0 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  :  Suspend Execu
2f8e0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2f8f0 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a   Time {F10530}.*
2f900 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f910 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2f920 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20  n.** causes the 
2f930 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2f940 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2f950 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2f960 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2f970 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2f980 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2f990 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2f9a0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2f9b0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2f9c0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2f9d0 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20  quests with .** 
2f9e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
2f9f0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
2fa00 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
2fa10 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
2fa20 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74   .** the nearest
2fa30 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
2fa40 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2fa50 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2fa60 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73  ually .** reques
2fa70 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2fa80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2fa90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2faa0 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
2fab0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
2fac0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
2fad0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
2fae0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
2faf0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
2fb00 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
2fb10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2fb20 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {F10533} The [s
2fb30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
2fb40 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
2fb50 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
2fb60 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
2fb70 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2fb80 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
2fb90 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
2fba0 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
2fbb0 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
2fbc0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
2fbd0 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
2fbe0 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
2fbf0 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
2fc00 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {F10536} The [s
2fc10 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
2fc20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fc30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
2fc50 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2fc60 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
2fc70 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
2fc80 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
2fc90 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
2fca0 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
2fcb0 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
2fcc0 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
2fcd0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
2fce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fcf0 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  F:  Name Of The 
2fd00 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2fd10 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
2fd20 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66  F10310}.**.** If
2fd30 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2fd40 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2fd50 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2fd60 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2fd70 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2fd80 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63  der (a.ka. direc
2fd90 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2fda0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2fdb0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2fdc0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
2fdd0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2fde0 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
2fdf0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e  variable.** is N
2fe00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2fe10 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20  n SQLite does a 
2fe20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
2fe30 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72  propriate tempor
2fe40 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65  ary.** file dire
2fe50 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
2fe60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
2fe70 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2fe80 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62  ble once a datab
2fe90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
2fea0 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
2feb0 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
2fec0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2fed0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2fee0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2fef0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2ff00 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2ff10 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2ff20 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2ff30 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2ff40 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
2ff50 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
2ff60 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
2ff70 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
2ff80 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
2ff90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ffa0 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20  F:  Test To See 
2ffb0 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20  If The Database 
2ffc0 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
2ffd0 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a  t Mode {F12930}.
2ffe0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2fff0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
30000 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  () interfaces re
30010 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
30020 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
30030 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
30040 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
30050 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
30060 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
30070 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41  espectively.   A
30080 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
30090 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75  s on.** by defau
300a0 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  lt.  Autocommit 
300b0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
300c0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
300d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
300e0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
300f0 65 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  eenabled by a [C
30100 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
30110 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
30120 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
30130 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
30140 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
30150 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
30160 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
30170 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63  ions (errors inc
30180 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
30190 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
301a0 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  ERR], .** [SQLIT
301b0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
301c0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
301d0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
301e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
301f0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
30200 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
30210 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
30220 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
30230 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c   find out if SQL
30240 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
30250 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
30260 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
30270 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
30280 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
30290 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
302a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
302b0 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73   {F12931} The [s
302c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
302d0 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66  ommit(D)] interf
302e0 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
302f0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20  zero or.**      
30300 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20      zero if the 
30310 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30320 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73  tion] D is or is
30330 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
30340 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
30350 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
30360 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32  y..**.** {F12932
30370 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
30380 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
30390 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  lt..**.** {F1293
303a0 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
303b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
303c0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
303d0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
303e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d  ..**.** {F12934}
303f0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
30400 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
30410 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
30420 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
30430 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
30440 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a  tatement..** .**
30450 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
30460 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d  .***.** {U12936}
30470 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
30480 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
30490 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
304a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
304b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
304c0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
304d0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
304e0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
304f0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
30500 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
30510 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
30520 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
30530 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
30540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30550 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
30560 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
30570 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30580 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a  nt {F13120}.**.*
30590 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
305a0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
305b0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
305c0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
305d0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77  base handle to w
305e0 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61  hich a.** [prepa
305f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
30600 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64  elongs..** The d
30610 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
30620 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30630 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20  e3_db_handle.** 
30640 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
30650 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
30660 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73   was.** the firs
30670 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30680 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30690 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
306a0 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74  variants.** that
306b0 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65   was used to cre
306c0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
306d0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
306e0 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lace..**.** INVA
306f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30700 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  13123} The [sqli
30710 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29  te3_db_handle(S)
30720 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
30730 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
30740 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
30750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30760 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
30770 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
30780 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
30790 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
307a0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
307b0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
307c0 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
307d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
307e0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
307f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
30800 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a  backs {F12950}.*
30810 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30820 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
30830 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30840 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30850 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30860 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30870 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30880 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30890 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
308a0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
308b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
308c0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
308d0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
308e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
308f0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
30900 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30910 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
30920 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30930 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30940 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30950 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30960 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30970 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30980 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
30990 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
309a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
309b0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
309c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
309d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
309e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
309f0 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
30a00 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
30a10 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
30a20 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
30a30 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
30a40 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
30a50 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
30a60 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
30a70 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
30a80 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
30a90 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
30aa0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
30ab0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
30ac0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
30ad0 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
30ae0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
30af0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
30b00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30b10 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
30b20 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
30b30 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
30b40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
30b50 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
30b60 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
30b70 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
30b80 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72   have been .** r
30b90 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
30ba0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
30bb0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
30bc0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
30bd0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
30be0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
30bf0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
30c00 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
30c10 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
30c20 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
30c30 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
30c40 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
30c50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
30c60 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
30c70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30c80 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
30c90 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
30ca0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
30cb0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
30cc0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
30cd0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
30ce0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
30cf0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
30d00 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
30d10 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
30d20 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
30d30 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72   These are exper
30d40 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
30d50 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65  es and are subje
30d60 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a  ct to change..**
30d70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
30d80 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54  **.** {F12951} T
30d90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
30da0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
30db0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
30dc0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
30dd0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
30de0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
30df0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
30e00 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
30e10 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
30e20 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
30e30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
30e40 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
30e50 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20  ** {F12952} The 
30e60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
30e70 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
30e80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30e90 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
30ea0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
30eb0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
30ec0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
30ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
30ee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30ef0 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
30f00 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
30f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
30f20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
30f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30f40 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
30f50 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
30f60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
30f70 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
30f80 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
30f90 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
30fa0 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
30fb0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
30fc0 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {F12954} If the 
30fd0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
30fe0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30ff0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
31000 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
31010 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
31020 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
31030 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f  cancelled and no
31040 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
31050 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
31060 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
31070 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a  ion commits..**.
31080 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74  ** {F12955} If t
31090 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61  he commit callba
310a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
310b0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ero then the com
310c0 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  mit is.**       
310d0 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74     converted int
310e0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
310f0 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65  .** {F12961} The
31100 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
31110 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
31120 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
31130 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
31140 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
31150 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
31160 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
31170 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
31180 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
31190 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
311a0 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ack on [database
311b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
311c0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54  **.** {F12962} T
311d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
311e0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
311f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
31200 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
31210 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
31220 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
31230 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
31240 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame .**         
31250 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31260 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e  ction ] D , or N
31270 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
31280 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
31290 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
312a0 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ar [database con
312b0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
312c0 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20  * {F12963} Each 
312d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
312e0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
312f0 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
31300 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
31310 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
31320 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
31330 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20  .**.** {F12964} 
31340 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
31350 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
31360 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
31370 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
31380 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
31390 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
313a0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
313b0 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c  lled and no call
313c0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
313d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
313e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72   a transaction r
313f0 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f  olls back..*/.vo
31400 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
31410 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
31420 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
31430 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
31440 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
31450 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
31460 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
31470 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
31480 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
31490 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
314a0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
314b0 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  970}.**.** The s
314c0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
314d0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ok() interface.*
314e0 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  * registers a ca
314f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
31500 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
31510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
31520 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
31530 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
31540 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
31550 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
31560 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
31570 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
31580 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
31590 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
315a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
315b0 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
315c0 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  same .** databas
315d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
315e0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
315f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
31600 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
31610 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
31620 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
31630 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
31640 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
31650 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a   or deleted. .**
31660 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
31670 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
31680 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79  ack is.** a copy
31690 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
316a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
316b0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
316c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
316d0 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75  allback .** argu
316e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
316f0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
31700 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
31710 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
31720 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  E],.** depending
31730 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
31740 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
31750 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65  e callback to be
31760 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65   invoked..** The
31770 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
31780 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
31790 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
317a0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
317b0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
317c0 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
317d0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
317e0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
317f0 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61  .** The final ca
31800 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
31810 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69   is .** the rowi
31820 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  d of the row..**
31830 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
31840 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
31850 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
31860 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74  er .** the updat
31870 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
31880 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
31890 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
318a0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
318b0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
318c0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
318d0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
318e0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
318f0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
31900 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
31910 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
31920 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
31930 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
31940 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
31950 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
31960 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31970 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31980 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20  ** {F12971} The 
31990 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
319a0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
319b0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
319c0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
319d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f     function F to
319e0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
319f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
31a00 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
31a10 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20          a table 
31a20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c  row is modified,
31a30 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65   inserted, or de
31a40 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  leted on.**     
31a50 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
31a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
31a70 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65  .** {F12973} The
31a80 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
31a90 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
31aa0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
31ab0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
31ac0 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74        of P for t
31ad0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
31ae0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
31af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31b00 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20  n] D,.**        
31b10 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68    or NULL for th
31b20 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a  e first call..**
31b30 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20  .** {F12975} If 
31b40 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  the update hook 
31b50 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73  callback F in [s
31b60 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31b70 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20  ok(D,F,P)].**   
31b80 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74         is NULL t
31b90 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74  hen the no updat
31ba0 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  e callbacks are 
31bb0 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  made..**.** {F12
31bc0 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  977} Each call t
31bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  o [sqlite3_updat
31be0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f  e_hook(D,F,P)] o
31bf0 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63  verrides prior c
31c00 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
31c10 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74   to the same int
31c20 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61  erface on the sa
31c30 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
31c40 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
31c50 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75  * {F12979} The u
31c60 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
31c70 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
31c80 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
31c90 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20   system.**      
31ca0 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20      tables such 
31cb0 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  as sqlite_master
31cc0 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
31cd0 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65  ence are modifie
31ce0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31  d..**.** {F12981
31cf0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
31d00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70  ameter to the up
31d10 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  date callback .*
31d20 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
31d30 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
31d40 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
31d50 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
31d60 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
31d70 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
31d80 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
31d90 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
31da0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
31db0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
31dc0 46 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  F12983} The thir
31dd0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
31de0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
31df0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
31e00 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
31e10 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
31e20 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
31e30 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
31e40 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
31e50 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
31e60 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
31e70 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
31e80 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38  ated...** {F1298
31e90 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
31ea0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
31eb0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
31ec0 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
31ed0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
31ee0 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
31ef0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
31f00 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
31f10 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
31f20 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
31f30 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
31f40 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
31f50 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
31f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31f70 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44  EF:  Enable Or D
31f80 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
31f90 67 65 72 20 43 61 63 68 65 20 7b 46 31 30 33 33  ger Cache {F1033
31fa0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
31fb0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
31fc0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
31fd0 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
31fe0 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
31ff0 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
32000 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
32010 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f  n connections to
32020 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
32030 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69  se..** Sharing i
32040 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
32050 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
32060 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  e and disabled i
32070 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  f the argument.*
32080 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  * is false..**.*
32090 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
320a0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
320b0 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61  isabled.** for a
320c0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
320d0 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20  . {END} This is 
320e0 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
320f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
32100 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72  5.0..** In prior
32110 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
32120 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73  ite, sharing was
32130 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  .** enabled or d
32140 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
32150 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
32160 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ly..**.** The ca
32170 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  che sharing mode
32180 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74   set by this int
32190 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61  erface effects a
321a0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  ll subsequent.**
321b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
321c0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
321d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
321e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
321f0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73  en16()]..** Exis
32200 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f  ting database co
32210 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  nnections contin
32220 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69  ue use the shari
32230 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20  ng mode.** that 
32240 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74  was in effect at
32250 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77   the time they w
32260 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  ere opened..**.*
32270 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
32280 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20   cannot be used 
32290 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61  with a shared ca
322a0 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72  che.   When shar
322b0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
322c0 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
322d0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
322e0 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
322f0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
32300 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
32310 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
32320 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
32330 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
32340 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
32350 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
32360 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
32370 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
32380 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
32390 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
323a0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
323b0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
323c0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
323d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
323e0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
323f0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
32400 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
32410 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
32420 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
32430 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
32440 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
32450 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
32460 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  citly..**.** INV
32470 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20  ARIANTS:.** .** 
32480 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63 63 65  {F10331} A succe
32490 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
324a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   of [sqlite3_ena
324b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
324c0 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (B)].**         
324d0 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20   will enable or 
324e0 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63  disable shared c
324f0 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e  ache mode for an
32500 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a  y subsequently.*
32510 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
32520 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
32530 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20  nection] in the 
32540 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  same process..**
32550 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65  .** {F10336} Whe
32560 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69  n shared cache i
32570 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
32580 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
32590 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  odule()].**     
325a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77       interface w
325b0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
325c0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
325d0 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b  * {F10337} The [
325e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
325f0 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20  hared_cache(B)] 
32600 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32610 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
32620 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
32630 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
32640 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
32650 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a  d successfully..
32660 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53  **.** {F10339} S
32670 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
32680 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
32690 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  lt..*/.int sqlit
326a0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
326b0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
326c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41  .** CAPI3REF:  A
326d0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
326e0 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33  eap Memory {F173
326f0 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
32700 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32710 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
32720 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20   attempts to.** 
32730 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
32740 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
32750 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
32760 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
32770 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  .** allocations 
32780 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
32790 62 61 73 65 20 6c 61 62 72 61 72 79 2e 20 7b 45  base labrary. {E
327a0 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  ND}  Memory used
327b0 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74  .** to cache dat
327c0 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69  abase pages to i
327d0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
327e0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
327f0 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e   of.** non-essen
32800 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71  tial memory.  Sq
32810 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32820 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a  mory() returns.*
32830 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32840 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
32850 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68  reed, which migh
32860 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
32870 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d  s.** than the am
32880 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
32890 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
328a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d  :.**.** {F17341}
328b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
328c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d  lease_memory(N)]
328d0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
328e0 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  pts to.**       
328f0 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 73 20     free N bytes 
32900 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
32910 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
32920 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20  on-essential.** 
32930 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
32940 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64  allocations held
32950 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
32960 20 6c 61 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   labrary..**.** 
32970 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71  {F16342} The [sq
32980 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32990 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73  mory(N)] returns
329a0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
329b0 20 20 20 20 20 20 20 20 6f 66 20 62 79 74 65 73          of bytes
329c0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
329d0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
329e0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20  more or less.** 
329f0 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 74 68           than th
32a00 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
32a10 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
32a20 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32a30 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
32a40 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65  API3REF:  Impose
32a50 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
32a60 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a   Size {F17350}.*
32a70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32a80 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
32a90 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
32aa0 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
32ab0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
32ac0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
32ad0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
32ae0 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53  llocated.** by S
32af0 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74  QLite. If an int
32b00 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e  ernal allocation
32b10 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a   is requested .*
32b20 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  * that would exc
32b30 65 65 64 20 74 68 65 20 73 6f 66 74 20 68 65 61  eed the soft hea
32b40 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65  p limit, [sqlite
32b50 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32b60 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65  ()] is.** invoke
32b70 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
32b80 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73  mes to free up s
32b90 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65  ome space before
32ba0 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a   the allocation.
32bb0 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  ** is made..**.*
32bc0 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63  * The limit is c
32bd0 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
32be0 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c  cause if.** [sql
32bf0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
32c00 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a  ory()] cannot.**
32c10 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
32c20 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
32c30 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
32c40 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
32c50 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
32c60 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
32c70 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
32c80 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
32c90 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  oceeds..**.** A 
32ca0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
32cb0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
32cc0 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
32cd0 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
32ce0 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
32cf0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
32d00 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
32d10 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
32d20 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
32d30 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ed..** The defau
32d40 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
32d50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32d60 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
32d70 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
32d80 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
32d90 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
32da0 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75  p limit.  .** Bu
32db0 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65  t if the soft he
32dc0 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20  ap limit cannot 
32dd0 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69  honored, executi
32de0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69  on will.** conti
32df0 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f  nue without erro
32e00 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f  r or notificatio
32e10 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20  n.  This is why 
32e20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a  the limit is .**
32e30 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
32e40 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
32e50 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
32e60 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
32e70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
32e80 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
32e90 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
32ea0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
32eb0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
32ec0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
32ed0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32ee0 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
32ef0 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
32f00 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
32f10 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
32f20 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
32f30 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
32f40 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
32f50 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
32f60 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
32f70 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32f80 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
32f90 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
32fa0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
32fb0 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
32fc0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
32fd0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
32fe0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
32ff0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
33000 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
33010 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
33020 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  reads..**.** INV
33030 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
33040 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16351} The [sql
33050 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
33060 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61  imit(N)] interfa
33070 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74  ce places a soft
33080 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
33090 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e     of N bytes on
330a0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
330b0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
330c0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
330d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69  .**          usi
330e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
330f0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
33100 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20  3_realloc()] at 
33110 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20  any point.**    
33120 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a        in time..*
33130 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66  *.** {F16352} If
33140 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
33150 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
33160 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
33170 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20  c()] would.**   
33180 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65         cause the
33190 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66   total amount of
331a0 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
331b0 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  y to exceed the.
331c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74  **          soft
331d0 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65   heap limit, the
331e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  n [sqlite3_relea
331f0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
33200 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20  invoked.**      
33210 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70      in an attemp
33220 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20  t to reduce the 
33230 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69  memory usage pri
33240 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67  or to proceeding
33250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
33260 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  h the memory all
33270 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e  ocation attempt.
33280 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20  .**.** {F16353} 
33290 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
332a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
332b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
332c0 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a  )] that trigger.
332d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65  **          atte
332e0 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d  mpts to reduce m
332f0 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f  emory usage thro
33300 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61  ugh the soft hea
33310 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  p limit.**      
33320 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f      mechanism co
33330 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74  ntinue even if t
33340 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  he attempt to re
33350 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  duce memory.**  
33360 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73          usage is
33370 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a   unsuccessful..*
33380 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20  *.** {F16354} A 
33390 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
333a0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20   value for N in 
333b0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
333c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
333d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
333e0 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  )] means that th
333f0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a  ere is no soft.*
33400 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20  *          heap 
33410 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74  limit and [sqlit
33420 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
33430 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
33440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
33450 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
33460 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65   is completely e
33470 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  xhausted..**.** 
33480 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66  {F16355} The def
33490 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
334a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
334b0 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
334c0 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20  * {F16358} Each 
334d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
334e0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
334f0 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  (N)] overrides t
33500 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
33510 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c  alues set by all
33520 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f   prior calls..*/
33530 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
33540 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
33550 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33560 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65  REF:  Extract Me
33570 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
33580 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
33590 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12850}.**.** 
335a0 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
335b0 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
335c0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
335d0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
335e0 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
335f0 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
33600 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
33610 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
33620 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
33630 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
33640 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
33650 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
33660 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
33670 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
33680 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
33690 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
336a0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
336b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
336c0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
336d0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
336e0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
336f0 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
33700 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
33710 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
33720 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
33730 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
33740 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
33750 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
33760 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
33770 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
33780 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
33790 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
337a0 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
337b0 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
337c0 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
337d0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
337e0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
337f0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
33800 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
33810 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
33820 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
33830 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
33840 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
33850 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
33860 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
33870 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
33880 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
33890 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
338a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
338b0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
338c0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
338d0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
338e0 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
338f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33900 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
33910 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
33920 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
33930 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
33940 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
33950 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
33960 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
33970 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
33980 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64  tion is ommitted
33990 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
339a0 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
339b0 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
339c0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
339d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
339e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
339f0 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
33a00 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
33a10 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
33a20 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
33a30 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
33a40 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
33a50 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
33a60 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
33a70 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
33a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
33a90 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
33aa0 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
33ab0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
33ac0 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
33ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
33ae0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
33af0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
33b00 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
33b10 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
33b20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
33b30 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
33b40 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
33b50 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
33b60 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
33b70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
33b80 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
33b90 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
33ba0 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
33bb0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
33bc0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33bd0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
33be0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
33bf0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
33c00 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
33c10 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
33c20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
33c30 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
33c40 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
33c50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
33c60 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
33c70 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
33c80 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
33c90 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
33ca0 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
33cb0 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
33cc0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
33cd0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
33ce0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
33cf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
33d00 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
33d10 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
33d20 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
33d30 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
33d40 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
33d50 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
33d60 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
33d70 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
33d80 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
33d90 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
33da0 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
33db0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
33dc0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33dd0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
33de0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
33df0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
33e00 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
33e10 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
33e20 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
33e30 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
33e40 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
33e50 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
33e60 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
33e70 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
33e80 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
33e90 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
33ea0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
33eb0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
33ec0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
33ed0 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
33ee0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
33ef0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
33f00 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
33f10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
33f20 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
33f30 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
33f40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
33f50 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
33f60 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
33f70 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
33f80 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
33f90 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
33fa0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
33fb0 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
33fc0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
33fd0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
33fe0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
33ff0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
34000 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
34010 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
34020 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
34030 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
34040 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
34050 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
34060 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
34070 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
34080 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
34090 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
340a0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
340b0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
340c0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
340d0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
340e0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
340f0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
34100 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
34110 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
34120 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
34130 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
34140 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
34150 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
34160 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
34170 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
34180 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
34190 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
341a0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
341b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
341c0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
341d0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
341e0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
341f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34200 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
34210 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
34220 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
34230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34240 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
34250 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a  ion {F12600}.**.
34260 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20  ** {F12601} The 
34270 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
34280 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
34290 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74  ce.** attempts t
342a0 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
342b0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
342c0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
342d0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
342e0 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20  e. {F12602} The 
342f0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
34300 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a  Proc. {F12603} z
34310 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a  Proc may be 0.**
34320 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
34330 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
34340 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
34350 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74  lts.** to "sqlit
34360 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
34370 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  t"..**.** {F1260
34380 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
34390 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
343a0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a  interface shall.
343b0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
343c0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
343d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
343e0 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
343f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
34400 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49  ** {F12605}.** I
34410 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
34420 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
34430 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
34440 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61  e.** sqlite3_loa
34450 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
34460 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
34470 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70  tempt to fill *p
34480 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
34490 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
344a0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
344b0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
344c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
344d0 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20  oc()]..** {END} 
344e0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
344f0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65  ction should fre
34500 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a  e this memory.**
34510 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
34520 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
34530 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20  .** {F12606}.** 
34540 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
34550 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
34560 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34570 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34580 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69  ension()].** pri
34590 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
345a0 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72  is API or an err
345b0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
345c0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
345d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
345e0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
345f0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
34600 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
34610 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
34620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34630 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
34640 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
34650 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
34660 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
34670 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
34680 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34690 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
346a0 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
346b0 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
346c0 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
346d0 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
346e0 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
346f0 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
34700 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
34710 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
34720 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
34730 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
34740 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  620}.**.** So as
34750 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
34760 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
34770 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
34780 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
34790 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
347a0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
347b0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
347c0 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
347d0 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
347e0 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
347f0 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
34800 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
34810 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
34820 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
34830 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
34840 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
34850 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
34860 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b  n and.** off.  {
34870 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66  F12622} It is of
34880 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45  f by default. {E
34890 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23  ND} See ticket #
348a0 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  1863..**.** {F12
348b0 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71  621} Call the sq
348c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
348d0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
348e0 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e  utine.** with on
348f0 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65  off==1 to turn e
34900 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
34910 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20   on.** and call 
34920 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
34930 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b   to turn it back
34940 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44   off again. {END
34950 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
34960 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34970 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
34980 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
34990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
349a0 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e   Make Arrangemen
349b0 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61  ts To Automatica
349c0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
349d0 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a  nsion {F12640}.*
349e0 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68  *.** {F12641} Th
349f0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  is function.** r
34a00 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
34a10 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
34a20 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
34a30 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
34a40 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
34a50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
34a60 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
34a70 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
34a80 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
34a90 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
34aa0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
34ab0 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  v2()]. {END}.**.
34ac0 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
34ad0 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
34ae0 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
34af0 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
34b00 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
34b10 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
34b20 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
34b30 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
34b40 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
34b50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
34b60 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
34b70 7b 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61  {F12642} Duplica
34b80 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
34b90 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
34ba0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
34bb0 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  ne multiple.** t
34bc0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
34bd0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
34be0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
34bf0 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f  {F12643} This ro
34c00 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
34c10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
34c20 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
34c30 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f  ray.** that is o
34c40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
34c50 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45  ite_malloc(). {E
34c60 4e 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61  ND} If you run a
34c70 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20   memory leak.** 
34c80 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20  checker on your 
34c90 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72  program and it r
34ca0 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65  eports a leak be
34cb0 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
34cc0 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76   array, then inv
34cd0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  oke [sqlite3_res
34ce0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
34cf0 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  n()] prior.** to
34d00 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65   shutdown to fre
34d10 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  e the memory..**
34d20 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74  .** {F12644} Aut
34d30 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
34d40 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
34d50 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
34d60 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
34d70 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
34d80 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
34d90 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
34da0 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
34db0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
34dc0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
34dd0 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
34de0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a  extension(void *
34df0 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a  xEntryPoint);...
34e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34e10 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
34e20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
34e30 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a  g {F12660}.**.**
34e40 20 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66   {F12661} This f
34e50 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
34e60 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
34e70 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75  registered.** au
34e80 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
34e90 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a  ns. {END}  This.
34ea0 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
34eb0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
34ec0 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74  all prior [sqlit
34ed0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34ee0 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a  n()].** calls..*
34ef0 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68  *.** {F12662} Th
34f00 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64  is call disabled
34f10 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
34f20 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  sions in all thr
34f30 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  eads. {END}.**.*
34f40 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
34f50 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
34f60 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
34f70 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
34f80 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
34f90 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
34fa0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
34fb0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
34fc0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
34fd0 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  ;.../*.****** EX
34fe0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
34ff0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
35000 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
35010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
35020 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
35030 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
35040 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
35050 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
35060 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
35070 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
35080 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
35090 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
350a0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
350b0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
350c0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
350d0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
350e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
350f0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
35100 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
35110 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
35120 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69  stablizes, we wi
35130 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
35140 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
35150 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
35160 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
35170 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
35180 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
35190 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
351a0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
351b0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
351c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
351d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
351e0 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
351f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
35200 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
35210 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
35220 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35230 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35240 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
35250 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
35260 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35270 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
35280 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
35290 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
352a0 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31  Table Object {F1
352b0 38 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  8000}.** KEYWORD
352c0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
352d0 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65  e.**.** A module
352e0 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76   is a class of v
352f0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20  irtual tables.  
35300 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64  Each module is d
35310 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20  efined.** by an 
35320 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
35330 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
35340 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63  ure.  This struc
35350 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a  ture consists.**
35360 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
35370 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
35380 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  e..*/.struct sql
35390 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
353a0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
353b0 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
353c0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
353d0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
353e0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
353f0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
35400 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
35410 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
35420 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
35430 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
35440 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
35450 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
35460 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
35470 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
35480 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
35490 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
354a0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
354b0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
354c0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
354d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
354e0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
354f0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
35500 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
35510 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35520 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35530 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
35540 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35550 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
35560 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35570 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
35580 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
35590 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
355a0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
355b0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
355c0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
355d0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
355e0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
355f0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
35600 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35610 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
35620 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
35630 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
35640 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
35650 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
35660 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
35670 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
35680 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
35690 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
356a0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
356b0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
356c0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
356d0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
356e0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
356f0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
35700 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
35710 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
35720 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
35730 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
35740 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
35750 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
35760 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
35770 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
35780 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35790 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
357a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
357b0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
357c0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
357d0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
357e0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
357f0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
35800 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
35810 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
35820 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
35830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35840 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
35850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35860 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35870 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
35880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
35890 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20  id **ppArg);..  
358a0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
358b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
358c0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
358d0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
358e0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
358f0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
35900 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46  g Information {F
35910 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18100}.** KEYWOR
35920 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
35930 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
35940 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35950 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
35960 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
35970 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
35980 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
35990 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
359a0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
359b0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
359c0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
359d0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
359e0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
359f0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
35a00 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
35a10 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
35a20 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
35a30 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
35a40 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
35a50 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
35a60 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
35a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
35a80 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
35a90 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
35aa0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
35ab0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
35ac0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
35ad0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
35ae0 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
35af0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
35b00 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
35b10 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
35b20 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
35b30 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
35b40 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
35b50 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
35b60 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
35b70 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
35b80 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
35b90 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
35ba0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
35bb0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
35bc0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
35bd0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
35be0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
35bf0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
35c00 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
35c10 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
35c20 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
35c30 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
35c40 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
35c50 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
35c60 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
35c70 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
35c80 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
35c90 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
35ca0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
35cb0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
35cc0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
35cd0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
35ce0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
35cf0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
35d00 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
35d10 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
35d20 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
35d30 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
35d40 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
35d50 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
35d60 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
35d70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
35d80 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
35d90 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
35da0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
35db0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
35dc0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
35dd0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
35de0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
35df0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
35e00 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
35e10 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
35e20 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
35e30 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
35e40 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
35e50 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
35e60 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
35e70 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
35e80 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
35e90 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
35ea0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
35eb0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
35ec0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
35ed0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
35ee0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
35ef0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
35f00 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
35f10 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
35f20 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
35f30 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
35f40 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
35f50 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
35f60 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
35f70 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
35f80 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
35f90 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
35fa0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
35fb0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
35fc0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
35fd0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
35fe0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
35ff0 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
36000 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
36010 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
36020 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
36030 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
36040 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
36050 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
36060 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
36070 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
36080 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
36090 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
360a0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
360b0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
360c0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
360d0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
360e0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
360f0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
36100 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
36110 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
36120 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
36130 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
36140 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
36150 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
36160 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
36170 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
36180 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
36190 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
361a0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
361b0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
361c0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
361d0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
361e0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
361f0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
36200 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
36210 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
36220 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
36230 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
36240 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
36250 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
36260 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
36270 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
36280 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
36290 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
362a0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
362b0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
362c0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
362d0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
362e0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
362f0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
36300 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
36310 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
36320 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
36330 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
36340 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
36350 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
36360 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
36370 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
36380 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
36390 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
363a0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
363b0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
363c0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
363d0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
363e0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
363f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
36400 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
36410 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
36420 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36430 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
36440 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
36450 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
36460 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
36470 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
36480 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
36490 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
364a0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
364b0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
364c0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
364d0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
364e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
364f0 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
36500 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36510 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
36520 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
36530 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
36540 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
36550 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
36560 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
36570 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
36580 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
36590 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
365a0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
365b0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
365c0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
365d0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
365e0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
365f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
36600 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
36610 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
36620 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
36630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36640 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
36650 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36660 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
36670 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
36680 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
36690 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
366a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
366b0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
366c0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
366d0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
366e0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
366f0 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
36700 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
36710 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
36720 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
36730 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
36740 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
36750 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36760 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
36770 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
36780 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36790 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
367a0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
367b0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
367c0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
367d0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
367e0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
367f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36800 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
36810 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
36820 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
36830 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
36840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36850 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
36860 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
36870 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d  ntation {F18200}
36880 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
36890 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
368a0 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f  egister a new mo
368b0 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61  dule name with a
368c0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e  n SQLite.** conn
368d0 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20  ection.  Module 
368e0 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65  names must be re
368f0 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20  gistered before 
36900 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20  creating new.** 
36910 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f  virtual tables o
36920 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72  n the module, or
36930 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72   before using pr
36940 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61  eexisting virtua
36950 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74  l.** tables of t
36960 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e  he module..*/.in
36970 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36980 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
36990 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
369a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
369b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
369c0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
369d0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
369e0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
369f0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36a00 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
36a10 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
36a20 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68  le *,    /* Meth
36a30 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
36a40 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20  le */.  void *  
36a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a60 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
36a70 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
36a80 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
36a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36aa0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
36ab0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
36ac0 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a  ation {F18210}.*
36ad0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
36ae0 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  e is identical t
36af0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
36b00 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65  eate_module() me
36b10 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65  thod above,.** e
36b20 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
36b30 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f  lows a destructo
36b40 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  r function to be
36b50 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69   specified. It i
36b60 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65  s.** even more e
36b70 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e  xperimental than
36b80 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65   the rest of the
36b90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
36ba0 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  API..*/.int sqli
36bb0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36bc0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
36bd0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36be0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
36bf0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
36c00 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
36c10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36c20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
36c30 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
36c40 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
36c50 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36c60 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
36c70 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
36c80 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
36c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ca0 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
36cb0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
36cc0 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
36cd0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
36ce0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
36cf0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
36d00 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
36d10 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36d20 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
36d30 4f 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d 0a  Object {F18010}.
36d40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
36d50 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
36d60 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
36d70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
36d80 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
36d90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
36da0 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
36db0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
36dc0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
36dd0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
36de0 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
36df0 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
36e00 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
36e10 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
36e20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36e30 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
36e40 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
36e50 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
36e60 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
36e70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
36e80 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
36e90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
36ea0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
36eb0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
36ec0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
36ed0 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
36ee0 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
36ef0 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
36f00 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
36f10 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
36f20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
36f30 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
36f40 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
36f50 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
36f60 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
36f70 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
36f80 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
36f90 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
36fa0 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
36fb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
36fc0 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
36fd0 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
36fe0 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
36ff0 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
37000 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
37010 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
37020 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
37030 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
37040 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
37050 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
37060 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37070 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
37080 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
37090 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
370a0 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
370b0 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
370c0 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
370d0 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
370e0 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
370f0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
37100 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
37110 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
37120 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
37130 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37140 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
37150 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
37160 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
37170 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
37180 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
37190 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
371a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
371b0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
371c0 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
371d0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
371e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
371f0 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
37200 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37210 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
37220 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37230 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37240 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37250 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37260 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37270 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
37280 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20  e Cursor Object 
37290 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59   {F18020}.** KEY
372a0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
372b0 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a  tab_cursor.**.**
372c0 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
372d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
372e0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
372f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
37300 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
37310 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37320 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37330 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
37340 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
37350 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
37360 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
37370 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
37380 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
37390 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68  he.** xOpen meth
373a0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
373b0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
373c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
373d0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
373e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
373f0 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
37400 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
37410 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
37420 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
37430 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
37440 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
37450 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
37460 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
37470 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
37480 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
37490 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
374a0 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
374b0 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
374c0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
374d0 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
374e0 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
374f0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37500 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37510 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37520 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37530 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37540 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
37550 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
37560 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32 38  ual Table {F1828
37570 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  0}.**.** The xCr
37580 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
37590 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d  t methods of a m
375a0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f  odule use the fo
375b0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74  llowing API.** t
375c0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
375d0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
375e0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
375f0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
37600 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
37610 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
37620 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
37630 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
37640 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
37650 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
37660 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Table);../*.** C
37670 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
37680 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
37690 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
376a0 20 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F18300}.**.** 
376b0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
376c0 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72  an provide alter
376d0 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
376e0 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69  ations of functi
376f0 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ons.** using the
37700 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d   xFindFunction m
37710 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62  ethod.  But glob
37720 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
37730 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
37740 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
37750 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
37760 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  loaded..**.** Th
37770 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
37780 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
37790 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
377a0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
377b0 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
377c0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
377d0 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
377e0 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
377f0 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
37800 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
37810 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
37820 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
37830 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
37840 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37850 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
37860 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
37870 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
37880 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
37890 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
378a0 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
378b0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
378c0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
378d0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
378e0 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75   place-holder fu
378f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
37900 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
37910 20 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c   by virtual tabl
37920 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  es..**.** This A
37930 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e  PI should be con
37940 73 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20  sidered part of 
37950 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
37960 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  e interface,.** 
37970 77 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d  which is experim
37980 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63  ental and subjec
37990 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
379a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
379b0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
379c0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
379d0 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
379e0 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
379f0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
37a00 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
37a10 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
37a20 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
37a30 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
37a40 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
37a50 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
37a60 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
37a70 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
37a80 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
37a90 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
37aa0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
37ab0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
37ac0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
37ad0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
37ae0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
37af0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
37b00 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
37b10 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
37b20 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
37b30 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
37b40 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
37b50 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
37b60 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
37b70 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
37b80 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
37b90 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  s comment..**.**
37ba0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
37bb0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
37bc0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
37bd0 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
37be0 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ***.*/../*.** CA
37bf0 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
37c00 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
37c10 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17800}.**.** 
37c20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
37c30 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
37c40 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
37c50 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69  OB on which.** i
37c60 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63  ncremental I/O c
37c70 61 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e  an be preformed.
37c80 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
37c90 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
37ca0 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
37cb0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
37cc0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
37cd0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
37ce0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
37cf0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
37d00 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
37d10 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
37d20 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
37d30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
37d40 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
37d50 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
37d60 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
37d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37d80 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
37d90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
37da0 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
37db0 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
37dc0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
37dd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
37de0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
37df0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
37e00 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
37e10 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37  emental I/O {F17
37e20 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  810}.**.** This 
37e30 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
37e40 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65   a handle to the
37e50 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a   blob located.**
37e60 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
37e70 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
37e80 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
37e90 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
37ea0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
37eb0 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
37ec0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
37ed0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
37ee0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
37ef0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
37f00 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
37f10 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
37f20 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
37f30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
37f40 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
37f50 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
37f60 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
37f70 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
37f80 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
37f90 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
37fa0 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
37fb0 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
37fc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
37fd0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
37fe0 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
37ff0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
38000 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
38010 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
38020 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
38030 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
38040 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73  se that.** is as
38050 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20  signed when the 
38060 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
38070 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
38080 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  ACH]..** For the
38090 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
380a0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
380b0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
380c0 2e 20 20 46 6f 72 0a 2a 2a 20 54 45 4d 50 20 74  .  For.** TEMP t
380d0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
380e0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
380f0 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  p"..**.** On suc
38100 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
38110 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
38120 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73  d the new .** [s
38130 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
38140 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  ob handle] is wr
38150 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
38160 2e 20 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  . .** Otherwise 
38170 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
38180 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a   returned and .*
38190 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74  * any value writ
381a0 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73  ten to *ppBlob s
381b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
381c0 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  d by the caller.
381d0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
381e0 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62  n sets the datab
381f0 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72  ase-handle error
38200 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
38210 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
38220 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
38230 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
38240 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
38250 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
38260 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33  S:.**.** {F17813
38270 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
38280 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
38290 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
382a0 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c  pen(D,B,T,C,R,F,
382b0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
382c0 69 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20  interface opens 
382d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  an [sqlite3_blob
382e0 5d 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68  ] object P on th
382f0 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20  e blob.**       
38300 20 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f     in column C o
38310 66 20 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74  f table T in dat
38320 61 62 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61  abase B on [data
38330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38340 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31   D..**.** {F1781
38350 34 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  4} A successful 
38360 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
38370 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
38380 28 44 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a  (D,...)] starts.
38390 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  **          a ne
383a0 77 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e  w transaction on
383b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
383c0 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74  ction] D if that
383d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
383e0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 61          is not a
383f0 6c 72 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e  lready in a tran
38400 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  saction..**.** {
38410 46 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c  F17816} The [sql
38420 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44  ite3_blob_open(D
38430 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69  ,B,T,C,R,F,P)] i
38440 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 74  nterface opens t
38450 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
38460 20 20 20 20 66 6f 72 20 72 65 61 64 20 61 6e 64      for read and
38470 20 77 72 69 74 65 20 61 63 63 65 73 73 20 69 66   write access if
38480 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
38490 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20   F parameter.** 
384a0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
384b0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  zero..**.** {F17
384c0 38 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  819} The [sqlite
384d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69  3_blob_open()] i
384e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
384f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
38500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63  .**          suc
38510 63 65 73 73 20 61 6e 64 20 61 6e 20 61 70 70 72  cess and an appr
38520 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
38530 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
38540 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 32 31 7d 20  .**.** {F17821} 
38550 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
38560 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
38570 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
38580 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e  _blob_open(D,...
38590 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  )].**          t
385a0 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63  hen subsequent c
385b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
385c0 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a  _errcode(D)],.**
385d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
385e0 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61  e3_errmsg(D)], a
385f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
38600 73 67 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65  sg16(D)] will re
38610 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
38620 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70   information app
38630 72 6f 70 72 61 74 65 20 66 6f 72 20 74 68 61 74  roprate for that
38640 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
38650 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
38660 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
38670 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
38680 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38690 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
386a0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
386b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
386c0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
386d0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
386e0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
386f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c  ** CAPI3REF:  Cl
38700 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
38710 65 20 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a  e {F17830}.**.**
38720 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b   Close an open [
38730 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
38740 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  lob handle]..**.
38750 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  ** Closing a BLO
38760 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
38770 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
38780 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
38790 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
387a0 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
387b0 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
387c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
387d0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
387e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
387f0 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  s in autocommit 
38800 6d 6f 64 65 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  mode..** If any 
38810 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
38820 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
38830 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
38840 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
38850 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
38860 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
38870 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a  ill fit. {END}.*
38880 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  * Closing the BL
38890 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
388a0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
388b0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
388c0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
388d0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
388e0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
388f0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
38900 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
38910 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38  s closed.  {F178
38920 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74  33} Any errors t
38930 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
38940 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
38950 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
38960 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
38970 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42  lue..**.** The B
38980 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e  LOB is