/ Hex Artifact Content
Login

Artifact abb785d2afcf45bb9344fe6edc1c7b428e1b719f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 33 31 30 20 32 30 30 38 2f  in,v 1.310 2008/
05f0: 30 34 2f 32 37 20 32 32 3a 34 38 3a 30 35 20 64  04/27 22:48:05 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 36 7d 20 41  **.** {F12766} 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 6e 65 67 61 74 69 76 65 0a 2a   V is negative.*
17f70 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65  *          leave
17f80 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 5b  s the state of [
17f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17fa0 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
17fb0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d  ..**.** {F12769}
17fc0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
17fd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
17fe0 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
17ff0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
18000 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
18010 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
18020 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
18030 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20   C in.**        
18040 20 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63    in [database c
18050 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20  onnection] D as 
18060 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20  it was prior to 
18070 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74  the call..*/.int
18080 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
18090 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
180a0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
180b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
180c0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
180d0 74 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30  tegories {F12790
180e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
180f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
18100 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
18110 73 7d 0a 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20  s}.** .** These 
18120 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
18130 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73   various aspects
18140 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   of a [database 
18150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
18160 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74  hat can be limit
18170 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61  ed in size by ca
18180 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18190 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
181a0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
181b0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
181c0 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
181d0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
181e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
181f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
18200 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
18210 7a 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72  ze of any.** str
18220 69 6e 67 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74  ing or blob or t
18230 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
18240 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18250 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
18260 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18270 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
18280 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
18290 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
182a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
182b0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
182c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
182d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
182e0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
182f0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
18300 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
18310 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68  f a SELECT or th
18320 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18330 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
18340 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
18350 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
18360 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
18370 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18380 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
18390 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
183a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
183b0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
183c0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
183d0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a  xpression.</dd>.
183e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
183f0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
18400 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
18410 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18420 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
18430 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
18440 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
18450 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18460 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
18470 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
18480 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18490 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
184a0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
184b0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
184c0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
184d0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
184e0 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
184f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18500 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
18510 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18520 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18530 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
18540 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  function.</dd>.*
18550 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18560 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
18570 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18580 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18590 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
185a0 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ses.</dd>.**.** 
185b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
185c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
185d0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
185e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
185f0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
18600 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
18610 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c  he LIKE or.** GL
18620 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  OB operators.</d
18630 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18640 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
18650 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
18660 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18670 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
18680 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
18690 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
186a0 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
186b0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
186c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
186d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
186e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
186f0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
18700 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
18710 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18720 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
18730 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
18740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18750 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
18760 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
18770 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
18780 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18790 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
187a0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
187b0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
187c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
187d0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
187e0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
187f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
18800 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
18810 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
18820 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
18830 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
18840 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
18850 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
18860 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
18870 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
18880 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
18890 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
188a0 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
188b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
188c0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
188d0 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
188e0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
188f0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
18900 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
18910 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
18920 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
18930 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
18940 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
18950 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  . .**.** The fir
18960 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22  st argument "db"
18970 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65   is an [database
18980 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a   connection] .**
18990 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
189a0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
189b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
189c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
189d0 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
189e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a  te3_open16()]. .
189f0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
18a00 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
18a10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
18a20 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
18a30 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
18a40 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
18a50 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
18a60 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
18a70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18a80 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
18a90 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
18aa0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
18ab0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
18ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18ad0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20  .** use UTF-16. 
18ae0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
18af0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
18b00 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
18b10 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
18b20 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
18b30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
18b40 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
18b50 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
18b60 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
18b70 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
18b80 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
18b90 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
18ba0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
18bb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
18bc0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
18bd0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
18be0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
18bf0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
18c00 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
18c10 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
18c20 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
18c30 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
18c40 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
18c50 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
18c60 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
18c70 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
18c80 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
18c90 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
18ca0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
18cb0 65 20 68 61 64 20 62 79 20 70 61 73 73 69 6e 67  e had by passing
18cc0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
18cd0 74 65 72 20 74 68 61 74 20 0a 2a 2a 20 69 73 20  ter that .** is 
18ce0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
18cf0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
18d00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
18d10 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
18d20 3e 20 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  > .** the nul-te
18d30 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b  rminator bytes.{
18d40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  END}.**.** *pzTa
18d50 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
18d60 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
18d70 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
18d80 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
18d90 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
18da0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
18db0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
18dc0 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72 73  ompiles the firs
18dd0 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
18de0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
18df0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
18e00 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
18e10 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
18e20 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
18e30 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
18e40 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
18e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
18e60 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
18e70 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
18e80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
18e90 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
18ea0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
18eb0 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74  ppStmt is.** set
18ec0 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
18ed0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
18ee0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
18ef0 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73   the input.** is
18f00 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e   and empty strin
18f10 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
18f20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
18f30 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
18f40 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {U13018} The cal
18f50 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
18f60 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
18f70 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a  r deleting the.*
18f80 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  * compiled SQL s
18f90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
18fa0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
18fb0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
18fc0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
18fd0 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
18fe0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
18ff0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
19000 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
19010 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
19020 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19030 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
19040 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
19050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19060 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
19070 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
19080 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
19090 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
190a0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
190b0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
190c0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
190d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
190e0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
190f0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
19100 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
19110 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
19120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19130 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
19140 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
19150 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
19160 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
19170 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67   of the .** orig
19180 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b  inal SQL text. {
19190 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73  END} This causes
191a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
191b0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
191c0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
191d0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
191e0 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
191f0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
19200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
19210 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
19220 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
19230 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
19240 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
19250 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
19260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19270 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
19280 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
19290 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
192a0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
192b0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
192c0 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
192d0 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
192e0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
192f0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
19300 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
19310 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19320 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
19330 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
19340 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
19350 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
19360 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  or, .** [SQLITE_
19370 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61  SCHEMA] is now a
19380 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
19390 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  alling.** [sqlit
193a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
193b0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
193c0 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
193d0 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
193e0 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
193f0 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
19400 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
19410 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
19420 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
19430 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
19440 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e  EMA] return. {EN
19450 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  D}.** </li>.**.*
19460 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
19470 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
19480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
19490 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
194a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
194b0 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  iled .** [error 
194c0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
194d0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
194e0 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79  . .** The legacy
194f0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
19500 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  at [sqlite3_step
19510 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
19520 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a  eturn a generic.
19530 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
19540 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e  ] result code an
19550 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
19560 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
19570 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  d call to.** [sq
19580 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
19590 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
195a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
195b0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
195c0 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  lem..** With the
195d0 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e   "v2" prepare in
195e0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
195f0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
19600 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
19610 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d  .** returned imm
19620 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
19630 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
19640 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
19650 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65  .** {F13011} The
19660 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19670 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  e(db,zSql,...)] 
19680 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19690 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
196a0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
196b0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
196c0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
196d0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
196e0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
196f0 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  ter as UTF-8..**
19700 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65  .** {F13012} The
19710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19720 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  e16(db,zSql,...)
19730 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
19740 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
19750 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  re16_v2(db,zSql,
19760 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
19770 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
19780 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
19790 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
197a0 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31  rameter as UTF-1
197b0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
197c0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
197d0 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68  * {F13013} If th
197e0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
197f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
19800 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
19810 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
19820 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
19830 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73  variants is less
19840 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
19850 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
19860 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
19870 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
19880 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
19890 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
198a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20  .**.** {F13014} 
198b0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
198c0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
198d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
198e0 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
198f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
19900 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
19910 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
19920 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
19930 65 73 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  es bytes.**     
19940 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73       SQL text is
19950 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
19960 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20  .**.** {F13015} 
19970 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  In [sqlite3_prep
19980 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
19990 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20  ,P,pzTail)] and 
199a0 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
199b0 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
199c0 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20  zSql input text 
199d0 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68  contains more th
199e0 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65  an one SQL state
199f0 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
19a00 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e   and pzTail is n
19a10 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70  ot NULL, then *p
19a20 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
19a30 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a   point to the.**
19a40 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
19a50 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
19a60 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
19a70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
19a80 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20  zSql..**        
19a90 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65    <todo>What doe
19aa0 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20  s *pzTail point 
19ab0 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f  to if there is o
19ac0 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74  ne statement?</t
19ad0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  odo>.**.** {F130
19ae0 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  16} A successful
19af0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19b00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
19b10 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e  zSql,N,ppStmt,..
19b20 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
19b30 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
19b40 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e  riants writes in
19b50 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69  to *ppStmt a poi
19b60 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
19b70 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
19b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
19b90 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  r a pointer to N
19ba0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
19bb0 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
19bc0 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
19bd0 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f  han whitespace o
19be0 72 20 63 6f 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a  r comments. .**.
19bf0 2a 2a 20 7b 46 31 33 30 31 39 7d 20 54 68 65 20  ** {F13019} The 
19c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19c10 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
19c20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
19c30 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
19c40 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
19c50 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
19c60 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
19c70 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
19c80 0a 2a 2a 20 7b 46 31 33 30 32 31 7d 20 42 65 66  .** {F13021} Bef
19c90 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
19ca0 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
19cb0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
19cc0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
19cd0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
19ce0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
19cf0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
19d00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
19d10 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ]).**          i
19d20 74 20 66 69 72 73 74 20 73 65 74 73 20 2a 70 70  t first sets *pp
19d30 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
19d40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
19d50 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
19d60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
19d70 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
19d80 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
19d90 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
19da0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
19db0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
19dc0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
19dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
19de0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
19df0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
19e00 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
19e10 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
19e20 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
19e30 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
19e40 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
19e50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
19e60 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
19e70 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
19e80 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
19e90 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
19ea0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
19eb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
19ec0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
19ed0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
19ee0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
19ef0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
19f00 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
19f10 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
19f20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
19f30 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
19f40 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
19f50 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
19f60 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
19f70 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
19f80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
19f90 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
19fa0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
19fb0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
19fc0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
19fd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
19fe0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
19ff0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a000 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a010 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1a020 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a030 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a040 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1a050 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a060 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a070 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a080 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a090 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a0a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a0b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a0c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a0d0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1a0e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a0f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a100 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a110 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a120 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1a130 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1a140 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1a150 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a160 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1a170 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1a180 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1a190 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1a1a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1a1b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1a1c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a1d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a1e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a1f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a200 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a210 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1a220 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a230 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a240 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a250 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1a260 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76  CAPIREF: Retriev
1a270 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
1a280 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a  L {F13100}.**.**
1a290 20 54 68 69 73 20 69 6e 74 65 72 65 66 61 63 65   This intereface
1a2a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a2b0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1a2c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1a2d0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1a2e0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1a2f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1a300 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49  tement]..**.** I
1a310 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1a320 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74 68 65   {F13101} If the
1a330 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a340 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1a350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a360 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1a370 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a380 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1a390 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1a3a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1a3b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a3c0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
1a3d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1a3e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
1a3f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
1a400 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a410 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a420 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
1a430 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1a440 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a450 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20  ng containing a 
1a460 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a  UTF-8 rendering.
1a470 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
1a480 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
1a490 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1a4a0 20 7b 46 31 33 31 30 32 7d 20 49 66 20 74 68 65   {F13102} If the
1a4b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a4c0 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1a4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a4e0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1a4f0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a500 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1a510 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1a520 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1a530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a540 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1a550 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1a560 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  re16()],.**     
1a570 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
1a580 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69  e3_sql()] functi
1a590 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  on returns a NUL
1a5a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1a5b0 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73 74   {F13103} The st
1a5c0 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
1a5d0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29   [sqlite3_sql(S)
1a5e0 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ] is valid until
1a5f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1a600 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a610 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74  ment] S is delet
1a620 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1a630 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a  3_finalize(S)]..
1a640 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1a650 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1a660 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1a670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a680 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  :  Dynamically T
1a690 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1a6a0 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b  t  {F15000}.** K
1a6b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1a6c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a6d0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1a6e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1a6f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1a700 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1a710 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1a720 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1a730 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1a740 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1a750 61 62 61 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20  abase table..** 
1a760 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1a770 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74  mic typing for t
1a780 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1a790 72 65 73 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73  res.  .** Values
1a7a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1a7b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1a7c0 20 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e   can be.** be in
1a7d0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1a7e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1a7f0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1a800 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1a810 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1a820 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1a830 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1a840 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1a850 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1a860 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1a870 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a880 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1a890 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1a8a0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1a8b0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1a8c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1a8d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1a8e0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1a8f0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1a900 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1a910 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 20 0a  ents specifies .
1a920 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1a930 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1a940 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1a950 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1a960 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1a970 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1a980 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1a990 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1a9a0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1a9b0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1a9c0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1a9d0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1a9e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1a9f0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1aa00 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1aa10 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1aa20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1aa30 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1aa40 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1aa50 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1aa60 65 64 0a 2a 2a 20 28 77 69 74 68 20 53 51 4c 49  ed.** (with SQLI
1aa70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 20  TE_THREADSAFE=0 
1aa80 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1aa90 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1aaa0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1aab0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1aac0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1aad0 77 65 65 6e 0a 2a 2a 20 70 72 6f 74 65 63 74 65  ween.** protecte
1aae0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1aaf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1ab00 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1ab10 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 20   can be.** used 
1ab20 69 6e 74 65 72 63 68 61 6e 67 61 62 6c 65 2e 20  interchangable. 
1ab30 20 48 6f 77 65 76 65 72 2c 20 66 6f 72 20 6d 61   However, for ma
1ab40 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
1ab50 62 69 6c 69 74 79 20 69 74 0a 2a 2a 20 69 73 20  bility it.** is 
1ab60 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1ab70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   applications ma
1ab80 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1ab90 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 62 65  on between.** be
1aba0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1abb0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20  and unprotected 
1abc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1abd0 6a 65 63 74 73 20 65 76 65 6e 20 69 66 0a 2a 2a  jects even if.**
1abe0 20 74 68 65 79 20 61 72 65 20 73 69 6e 67 6c 65   they are single
1abf0 20 74 68 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a   threaded..**.**
1ac00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1ac10 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1ac20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1ac30 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1ac40 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1ac50 69 6f 6e 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ion of applicati
1ac60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1ac70 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 70 72 6f  unctions are pro
1ac80 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
1ac90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1aca0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1acb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1acc0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1acd0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1ace0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1acf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ad00 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1ad10 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1ad20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1ad30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ad40 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20  bind_value()].  
1ad50 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  All other.** int
1ad60 65 72 66 61 63 65 73 20 74 68 61 74 20 75 73 65  erfaces that use
1ad70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 72   sqlite3_value r
1ad80 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1ad90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ada0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1adb0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1adc0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1add0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
1ade0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
1adf0 65 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30  ext Object {F160
1ae00 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  01}.**.** The co
1ae10 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1ae20 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1ae30 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1ae40 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1ae50 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1ae60 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1ae70 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1ae80 65 78 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  ext.** object is
1ae90 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1aea0 72 61 6d 65 74 65 72 20 74 6f 20 61 70 70 6c 69  rameter to appli
1aeb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1aec0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f  QL functions..*/
1aed0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1aee0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1aef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1af00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1af10 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  :  Binding Value
1af20 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
1af30 61 74 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30  atements {F13500
1af40 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1af50 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1af60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1af70 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1af80 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20  ts.** variants, 
1af90 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1afa0 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72  replace by a par
1afb0 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a  ameter in one.**
1afc0 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
1afd0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1afe0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
1aff0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
1b000 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
1b010 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
1b020 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
1b030 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
1b040 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
1b050 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
1b060 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56  er literal,.** V
1b070 56 56 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63  VV alpha-numeric
1b080 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e   parameter name.
1b090 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f  .** The values o
1b0a0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
1b0b0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1b0c0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1b0d0 6e 61 6d 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51  names".** or "SQ
1b0e0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1b0f0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1b100 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1b110 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1b120 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1b130 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1b140 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
1b150 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1b160 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 0a  routines always.
1b170 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
1b180 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1b190 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
1b1a0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
1b1b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b1c0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
1b1d0 61 6e 74 73 2e 20 54 68 65 20 73 65 63 6f 6e 64  ants. The second
1b1e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
1b1f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1b200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
1b210 20 73 65 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72   set. The.** fir
1b220 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1b230 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
1b240 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e   When the same n
1b250 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  amed.** paramete
1b260 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1b270 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1b280 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1b290 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1b2a0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1b2b0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1b2c0 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20  occurrence. .** 
1b2d0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
1b2e0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
1b2f0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
1b300 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
1b310 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b320 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49  eter_name()] API
1b330 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1b340 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1b350 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1b360 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1b370 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1b380 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1b390 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1b3a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1b3b0 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
1b3c0 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
1b3d0 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
1b3e0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1b3f0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1b400 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1b410 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1b420 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b430 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f  * In those.** ro
1b440 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1b450 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1b460 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1b470 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1b480 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70  ytes.** in the p
1b490 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1b4a0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1b4b0 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
1b4c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a  of <u>bytes</u>.
1b4d0 2a 2a 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  ** in the value,
1b4e0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1b4f0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20 0a  of characters. .
1b500 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
1b510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1b520 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1b530 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1b540 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66   is.** number of
1b550 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1b560 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1b570 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1b580 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1b590 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1b5a0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1b5b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1b5c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1b5d0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1b5e0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1b5f0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1b600 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1b610 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1b620 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b630 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1b640 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1b650 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1b660 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1b670 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1b680 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1b690 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1b6a0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1b6b0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1b6c0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1b6d0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1b6e0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1b6f0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1b700 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1b710 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1b720 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1b730 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1b740 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1b750 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1b760 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1b770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1b780 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1b790 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1b7a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1b7b0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1b7c0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1b7d0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1b7e0 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  d with zeros.  A
1b7f0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
1b800 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
1b810 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
1b820 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
1b830 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69  old it size) whi
1b840 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1b850 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1b860 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1b870 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1b880 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1b890 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
1b8a0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
1b8b0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
1b8c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1b8d0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1b8e0 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
1b8f0 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76  tines. A negativ
1b900 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74  e.** value for t
1b910 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1b920 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1b930 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1b940 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1b950 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
1b960 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
1b970 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
1b980 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
1b990 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
1b9a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1b9b0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
1b9c0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
1b9d0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
1b9e0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1b9f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1ba00 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1ba10 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
1ba20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1ba30 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1ba40 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
1ba50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1ba60 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1ba70 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
1ba80 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
1ba90 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1baa0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
1bab0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1bac0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1bad0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1bae0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
1baf0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1bb00 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66  rned if malloc f
1bb10 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
1bb20 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
1bb30 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
1bb40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1bb50 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
1bb60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1bb70 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
1bb80 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
1bb90 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
1bba0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
1bbb0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
1bbc0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
1bbd0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
1bbe0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
1bbf0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
1bc00 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
1bc10 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
1bc20 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
1bc30 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
1bc40 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
1bc50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
1bc60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1bc70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1bc80 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
1bc90 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
1bca0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
1bcb0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1bcc0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1bcd0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
1bce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bcf0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
1bd00 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1bd10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1bd20 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
1bd30 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1bd40 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73   {F13506} The [s
1bd50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1bd60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
1bd70 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69  ompiler] recogni
1bd80 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zes.**          
1bd90 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f  tokens of the fo
1bda0 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  rms "?", "?NNN",
1bdb0 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c   "$VVV", ":VVV",
1bdc0 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20   and "@VVV".**  
1bdd0 20 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 70          as SQL p
1bde0 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65  arameters, where
1bdf0 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75   NNN is any sequ
1be00 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
1be10 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
1be20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 65  digits and where
1be30 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75   VVV is any sequ
1be40 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
1be50 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ore .**         
1be60 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68   alphanumeric ch
1be70 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
1be80 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
1be90 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  owed by.**      
1bea0 20 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e      a string con
1beb0 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65  taining no space
1bec0 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
1bed0 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
1bee0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30  es..**.** {F1350
1bef0 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
1bf00 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
1bf10 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
1bf20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d  ..**.** {F13512}
1bf30 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
1bf40 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
1bf50 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
1bf60 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
1bf70 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
1bf80 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
1bf90 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
1bfa0 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
1bfb0 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
1bfc0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
1bfd0 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
1bfe0 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20  ** {F13515} The 
1bff0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
1c000 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
1c010 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
1c020 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  NNN..**.** {F135
1c030 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
1c040 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
1c050 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
1c060 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
1c070 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
1c080 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
1c090 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
1c0a0 75 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20 73  urances of the s
1c0b0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1c0c0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e  parameter, or on
1c0d0 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20  e more than the 
1c0e0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76  largest index ov
1c0f0 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  er all.**       
1c100 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f     parameters to
1c110 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69   the left if thi
1c120 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f  s is the first o
1c130 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20  ccurrance.**    
1c140 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61        of this pa
1c150 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66  rameter, or 1 if
1c160 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66   this is the lef
1c170 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e  tmost parameter.
1c180 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20  .**.** {F13521} 
1c190 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1c1a0 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65  pare | SQL state
1c1b0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
1c1c0 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ail with.**     
1c1d0 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f       an [SQLITE_
1c1e0 52 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20  RANGE] error if 
1c1f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
1c200 53 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  SQL parameter.**
1c210 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73            is les
1c220 73 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61  s than 1 or grea
1c230 74 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f  ter than SQLITE_
1c240 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c250 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  BER..**.** {F135
1c260 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  24} Calls to [sq
1c270 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1c280 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1c290 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,V,...)].**   
1c2a0 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65         associate
1c2b0 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74   the value V wit
1c2c0 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  h all SQL parame
1c2d0 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a  ters having an.*
1c2e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78  *          index
1c2f0 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72   of N in the [pr
1c300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c310 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ] S..**.** {F135
1c320 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  27} Calls to [sq
1c330 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1c340 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1c350 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
1c360 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72       override pr
1c370 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74  ior calls with t
1c380 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f  he same values o
1c390 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a  f S and N..**.**
1c3a0 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e   {F13530} Bindin
1c3b0 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62  gs established b
1c3c0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
1c3d0 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
1c3e0 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  ind(S,...)].**  
1c3f0 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20          persist 
1c400 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20  across calls to 
1c410 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
1c420 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  )]..**.** {F1353
1c430 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  3} In calls to [
1c440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1c450 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
1c460 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c470 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1c480 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
1c490 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c4a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1c4b0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
1c4c0 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73  e binds the firs
1c4d0 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t L.**          
1c4e0 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f  bytes of the blo
1c4f0 62 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e  b or string poin
1c500 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65  ted to by V, whe
1c510 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n L.**          
1c520 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
1c530 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20  .**.** {F13536} 
1c540 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c550 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
1c560 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a  ,N,V,L,D)] or.**
1c570 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c580 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1c590 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74  ,N,V,L,D)] SQLit
1c5a0 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65  e binds characte
1c5b0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  rs.**          f
1c5c0 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68  rom V through th
1c5d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
1c5e0 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73  racter when L is
1c5f0 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   negative..**.**
1c600 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c   {F13539} In cal
1c610 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1c620 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1c630 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1c640 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c650 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1c660 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1c670 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c680 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1c690 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
1c6a0 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
1c6b0 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
1c6c0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51  LITE_STATIC], SQ
1c6d0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
1c6e0 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a  t the value V.**
1c6f0 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c            is hel
1c700 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61  d in static unma
1c710 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74  naged space that
1c720 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65   will not change
1c730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
1c740 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
1c750 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e   of the binding.
1c760 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20  .**.** {F13542} 
1c770 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c780 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
1c790 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
1c7a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c7b0 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
1c7c0 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
1c7d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c7e0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c7f0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
1c800 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a  s the special.**
1c810 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61            consta
1c820 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nt [SQLITE_TRANS
1c830 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69  IENT], the routi
1c840 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20  ne makes a .**  
1c850 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
1c860 63 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20  copy of V value 
1c870 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
1c880 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35  s..**.** {F13545
1c890 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1c8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1c8b0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1c8c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c8d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1c8e0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1c8f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c900 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1c910 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1c920 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1c930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
1c940 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  unction, SQLite 
1c950 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e  invokes that fun
1c960 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79  ction to destroy
1c970 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c980 20 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69   V value after i
1c990 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
1c9a0 73 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65  sing the V value
1c9b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d  ..**.** {F13548}
1c9c0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1c9d0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1c9e0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68  lob(S,N,V,L)] th
1c9f0 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a  e value bound.**
1ca00 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62            is a b
1ca10 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20  lob of L bytes, 
1ca20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
1ca30 20 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65   blob if L is ne
1ca40 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1ca50 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20  13551} In calls 
1ca60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1ca70 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74  _value(S,N,V)] t
1ca80 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61  he V argument ma
1ca90 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  y.**          be
1caa0 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65   either a [prote
1cab0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1cac0 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e  ue] object or an
1cad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e  .**          [un
1cae0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1caf0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
1cb00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cb10 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1cb20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cb30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1cb40 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cb50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cb60 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1cb70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1cb80 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1cb90 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1cba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1cbb0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1cbc0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1cbd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1cbe0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1cbf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1cc00 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1cc10 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1cc20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1cc30 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1cc40 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1cc50 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1cc60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1cc70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1cc80 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1cc90 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1cca0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1ccb0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1ccc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1ccd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1cce0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1ccf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1cd00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1cd10 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1cd20 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1cd30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cd40 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1cd50 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31  L Parameters {F1
1cd60 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3600}.**.** This
1cd70 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1cd80 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1cd90 20 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70   number of SQL p
1cda0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20  arameters.** in 
1cdb0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
1cdc0 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d  ment.  SQL param
1cdd0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
1cde0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
1cdf0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
1ce00 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
1ce10 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
1ce20 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f  e as.** place-ho
1ce30 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
1ce40 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
1ce50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1ce60 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
1ce70 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
1ce80 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
1ce90 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
1cea0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
1ceb0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1cec0 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74   largest paramet
1ced0 65 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66  er..** For all f
1cee0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
1cef0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
1cf00 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75  espond to the nu
1cf10 6d 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75  mber of.** uniqu
1cf20 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
1cf30 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
1cf40 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65  the ?NNN are use
1cf50 64 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20  d, there may.** 
1cf60 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1cf70 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ist..**.** See a
1cf80 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1cf90 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1cfa0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1cfb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cfc0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1cfd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1cfe0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1cff0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1d000 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1d010 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  13601} The [sqli
1d020 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d030 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  er_count(S)] int
1d040 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
1d050 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
1d060 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20  argest index of 
1d070 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
1d080 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  rs in the.**    
1d090 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1d0a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72  statement] S, or
1d0b0 20 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20   0 if S.**      
1d0c0 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20      contains no 
1d0d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
1d0e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1d0f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1d100 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1d110 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d120 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1d130 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46  ost Parameter {F
1d140 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13620}.**.** Thi
1d150 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1d160 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1d170 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1d180 2d 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  -th.** SQL param
1d190 65 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61  eter in a [prepa
1d1a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1d1b0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
1d1c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
1d1d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1d1e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1d1f0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
1d200 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
1d210 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
1d220 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1d230 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
1d240 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
1d250 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
1d260 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
1d270 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
1d280 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
1d290 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
1d2a0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
1d2b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1d2c0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1d2d0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1d2e0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  r have no name..
1d2f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1d300 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1d310 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1d320 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  , not 0..**.** I
1d330 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73  f the value n is
1d340 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
1d350 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   if the n-th par
1d360 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
1d370 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
1d380 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
1d390 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1d3a0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
1d3b0 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  in the UTF-8 enc
1d3c0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
1d3d0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
1d3e0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
1d3f0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
1d400 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
1d410 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1d420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1d430 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1d440 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d450 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1d460 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1d470 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1d480 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d490 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1d4a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d4b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1d4c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1d4d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1d4e0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
1d4f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d500 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1d510 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
1d520 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38           a UTF-8
1d530 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1d540 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
1d550 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  L parameter in.*
1d560 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
1d570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d580 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e  S having index N
1d590 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1d5a0 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
1d5b0 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74  s no SQL paramet
1d5c0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
1d5d0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  or if the.**    
1d5e0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
1d5f0 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20  with index N is 
1d600 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  an anonymous par
1d610 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63  ameter "?"..*/.c
1d620 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1d630 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d640 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
1d650 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
1d660 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
1d670 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
1d680 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
1d690 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a  ame {F13640}.**.
1d6a0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
1d6b0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1d6c0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
1d6d0 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
1d6e0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1d6f0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1d700 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1d710 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1d720 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1d730 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1d740 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
1d750 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
1d760 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
1d770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
1d780 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
1d790 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1d7a0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1d7b0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1d7c0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1d7d0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1d7e0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1d7f0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1d800 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1d810 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1d820 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1d830 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1d840 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1d850 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d860 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1d870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1d880 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1d890 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1d8a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1d8b0 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
1d8c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d8d0 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
1d8e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1d8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1d900 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
1d910 61 6d 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61  ameter in [prepa
1d920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1d930 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
1d940 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
1d950 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
1d960 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
1d970 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
1d980 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
1d990 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1d9a0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1d9b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1d9c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1d9d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d9e0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1d9f0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1da00 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  red Statement {F
1da10 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e  13660}.**.** Con
1da20 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
1da30 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
1da40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1da50 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65  ] does not.** re
1da60 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  set the [sqlite3
1da70 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
1da80 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20  dings] on a .** 
1da90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1daa0 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20  ent].  Use this 
1dab0 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65  routine to.** re
1dac0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1dad0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1dae0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1daf0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31  S:.**.** {F13661
1db00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1db10 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29  lear_bindings(S)
1db20 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
1db30 74 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  ts all.**       
1db40 20 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72     SQL parameter
1db50 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72   bindings in [pr
1db60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1db70 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] S.**          
1db80 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
1db90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
1dba0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
1dbb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1dbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1dbd0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
1dbe0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1dbf0 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13710}.**.** Re
1dc00 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1dc10 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1dc20 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
1dc30 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  urned by the .**
1dc40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dc50 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
1dc60 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a  ine returns 0.**
1dc70 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1dc80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
1dc90 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
1dca0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a  rn data (for .**
1dcb0 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41   example an UPDA
1dcc0 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  TE)..**.** INVAR
1dcd0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1dce0 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
1dcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1dd00 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
1dd10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1dd20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1dd30 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
1dd40 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
1dd50 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ted by the.**   
1dd60 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1dd70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f   statement] S, o
1dd80 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
1dd90 74 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20  t generate.**   
1dda0 20 20 20 20 20 20 20 61 20 72 65 73 75 6c 74 20         a result 
1ddb0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1ddc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
1ddd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1dde0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1ddf0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
1de00 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
1de10 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a   Set {F13720}.**
1de20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1de30 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
1de40 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
1de50 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
1de60 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
1de70 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
1de80 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
1de90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1dea0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
1deb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
1dec0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1ded0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1dee0 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  F8 string.** and
1def0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1df00 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
1df10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1df20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1df30 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  ** UTF16 string.
1df40 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1df50 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1df60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1df70 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d  ent] that implem
1df80 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20  ents the SELECT 
1df90 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1dfa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1dfb0 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e  er is the column
1dfc0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1dfd0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
1dfe0 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  s.** number 0..*
1dff0 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  *.** The returne
1e000 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
1e010 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1e020 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b  either the .** [
1e030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e040 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1e050 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
1e060 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
1e070 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
1e080 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
1e090 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
1e0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e0b0 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
1e0c0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
1e0d0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
1e0e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
1e0f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
1e100 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
1e110 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
1e120 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
1e130 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
1e140 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
1e150 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1e160 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
1e170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
1e180 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
1e190 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
1e1a0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
1e1b0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
1e1c0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
1e1d0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
1e1e0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
1e1f0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
1e200 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
1e210 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
1e220 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
1e230 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
1e240 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
1e250 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
1e260 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
1e270 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1e280 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
1e290 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
1e2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1e2b0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
1e2c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1e2d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1e2e0 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1e2f0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
1e300 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74  mn (where 0 is t
1e310 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
1e320 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20  umn) for the.** 
1e330 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
1e340 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
1e350 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
1e360 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
1e370 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e380 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1e390 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75  ** {F13723} A su
1e3a0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1e3b0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
1e3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e3d0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
1e3e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
1e3f0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
1e400 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1e410 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
1e420 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
1e430 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
1e440 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
1e450 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
1e460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e470 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
1e480 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1e490 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
1e4a0 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61  string in the na
1e4b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1e4c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20  .**.** {F13724} 
1e4d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1e4e0 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
1e4f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e500 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
1e510 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1e520 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
1e530 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
1e540 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
1e550 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
1e560 65 20 6d 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20  e memory memory 
1e570 74 6f 20 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f  to hold there no
1e580 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69  rmal return stri
1e590 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ngs..**.** {F137
1e5a0 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  25} If the N par
1e5b0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1e5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e5d0 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
1e5e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1e5f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1e600 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1e610 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
1e620 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1e630 73 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  s returns a NULL
1e640 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a   pointer..** .**
1e650 20 7b 46 31 33 37 32 36 7d 20 54 68 65 20 73 74   {F13726} The st
1e660 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1e670 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1e680 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64  n_name(S,N)] and
1e690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1e6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e6b0 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61  e16(S,N)] are va
1e6c0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1e6d0 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  xt.**          c
1e6e0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f  all to either ro
1e6f0 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73  utine with the s
1e700 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61  ame S and N para
1e710 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  meters.**       
1e720 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c     or until [sql
1e730 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
1e740 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  ] is called..**.
1e750 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e  ** {F13727} When
1e760 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1e770 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1e780 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e  tatement contain
1e790 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
1e7a0 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20   AS clause, the 
1e7b0 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c  name of that col
1e7c0 75 6d 6e 20 69 73 20 74 68 65 20 69 6e 64 65 6e  umn is the inden
1e7d0 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
1e7e0 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
1e7f0 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
1e800 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
1e810 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e820 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1e830 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
1e840 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1e850 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
1e860 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e870 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
1e880 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
1e890 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
1e8a0 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d   Result {F13740}
1e8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1e8c0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
1e8d0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
1e8e0 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
1e8f0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
1e900 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
1e910 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
1e920 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1e930 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
1e940 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
1e950 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
1e960 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
1e970 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
1e980 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20  * either a UTF8 
1e990 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  or UTF16 string.
1e9a0 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
1e9b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e9c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e9d0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
1e9e0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
1e9f0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
1ea00 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
1ea10 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
1ea20 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
1ea30 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
1ea40 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1ea50 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
1ea60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1ea70 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1ea80 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
1ea90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1eaa0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1eab0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1eac0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1ead0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1eae0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1eaf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1eb00 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1eb10 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1eb20 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1eb30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1eb40 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1eb50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1eb60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1eb70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1eb80 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1eb90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1eba0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1ebb0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1ebc0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1ebd0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1ebe0 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
1ebf0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
1ec00 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
1ec10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1ec20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
1ec30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1ec40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
1ec50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
1ec60 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
1ec70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
1ec80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
1ec90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
1eca0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
1ecb0 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  urn NULL.  These
1ecc0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
1ecd0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
1ece0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
1ecf0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
1ed00 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
1ed10 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
1ed20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  the .** name of 
1ed30 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
1ed40 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64  abase, table and
1ed50 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1ed60 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  ry result.** col
1ed70 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
1ed80 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
1ed90 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
1eda0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
1edb0 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
1edc0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1edd0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1ede0 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
1edf0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
1ee00 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
1ee10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
1ee20 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
1ee30 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
1ee40 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
1ee50 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
1ee60 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
1ee70 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
1ee80 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1ee90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1eea0 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  U13751}.** If tw
1eeb0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1eec0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1eed0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1eee0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1eef0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1ef00 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1ef10 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1ef20 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1ef30 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1ef40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1ef50 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1ef60 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20  ** {F13741} The 
1ef70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ef80 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c  database_name(S,
1ef90 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1efa0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1efb0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1efc0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1efd0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
1efe0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69  atabase from whi
1eff0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f000 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f010 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f040 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f050 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f060 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f070 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f080 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f090 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f0a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f0b0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f0c0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f0d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f0e0 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {F13742} The [s
1f0f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f100 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
1f110 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1f120 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1f130 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1f140 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
1f150 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
1f160 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1f170 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
1f180 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
1f190 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1f1a0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1f1b0 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1f1c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1f1d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1f1e0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1f1f0 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1f200 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1f210 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1f220 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1f230 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1f240 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1f250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1f260 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1f270 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1f280 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {F13743} The [sq
1f290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1f2a0 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
1f2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f2c0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1f2d0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1f2e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1f2f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1f300 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f310 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f320 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f330 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f340 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f350 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f360 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f370 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f380 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f390 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f3a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f3b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f3c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f3d0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f3e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f3f0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d      .** {F13744}
1f400 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f410 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
1f420 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
1f430 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1f440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f450 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
1f460 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
1f470 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1f480 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1f490 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
1f4a0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f4b0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f4c0 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f4d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f4f0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f500 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f510 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f520 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f530 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f540 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f550 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f560 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f570 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f590 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {F13745} The [s
1f5a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1f5b0 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
1f5c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1f5d0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1f5e0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
1f5f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1f600 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
1f610 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
1f620 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1f630 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1f640 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1f650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f670 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1f680 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1f690 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1f6a0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1f6b0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1f6c0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1f6d0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1f6e0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1f6f0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1f700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1f710 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {F13746} The [s
1f720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1f730 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
1f740 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1f750 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1f760 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1f770 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1f780 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1f790 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f7a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
1f7b0 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
1f7c0 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1f7d0 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1f7e0 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1f7f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1f800 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1f810 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1f820 55 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e  ULL if the the N
1f830 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
1f840 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1f850 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
1f860 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
1f870 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1f880 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
1f890 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
1f8a0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
1f8b0 2a 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72  * {F13748} The r
1f8c0 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
1f8d0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
1f8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f8f0 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
1f900 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
1f910 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
1f920 20 20 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a      are valid.**
1f930 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
1f940 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
1f950 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f960 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
1f970 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20     or until the 
1f980 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e  encoding is chan
1f990 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d  ged by another m
1f9a0 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
1f9b0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
1f9c0 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ll for the same 
1f9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f9e0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  nt and column..*
1f9f0 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
1fa00 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  :.**.** {U13751}
1fa10 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
1fa20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
1fa30 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
1fa40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1fa50 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1fa60 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1fa70 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1fa80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
1fa90 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
1faa0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
1fab0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
1fac0 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
1fad0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1fae0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1faf0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
1fb00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1fb10 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1fb20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fb30 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fb40 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fb50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1fb60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1fb70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
1fb80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1fb90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
1fba0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1fbb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1fbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1fbd0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
1fbe0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1fbf0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fc00 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1fc10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fc20 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fc30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fc40 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
1fc50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1fc60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1fc70 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
1fc80 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
1fc90 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36  ry Result {F1376
1fca0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0}.**.** The fir
1fcb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1fcc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fcd0 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74  ement]. .** If t
1fce0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1fcf0 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
1fd00 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
1fd10 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a  column of the .*
1fd20 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
1fd30 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53 45  t set of that SE
1fd40 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20  LECT is a table 
1fd50 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
1fd60 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
1fd70 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
1fd80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
1fd90 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
1fda0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
1fdb0 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
1fdc0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
1fdd0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
1fde0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
1fdf0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
1fe00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
1fe10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
1fe20 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1fe30 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
1fe40 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e  -8 encoded.  {EN
1fe50 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  D} .** For examp
1fe60 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62  le, in the datab
1fe70 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1fe80 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1fe90 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1fea0 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c  *.** And the fol
1feb0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1fec0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
1fed0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
1fee0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
1fef0 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * Then this rout
1ff00 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
1ff10 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
1ff20 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
1ff30 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63  cond.** result c
1ff40 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
1ff50 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
1ff60 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
1ff70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
1ff80 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
1ff90 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
1ffa0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
1ffb0 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
1ffc0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
1ffd0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
1ffe0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
1fff0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
20000 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
20010 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
20020 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
20030 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
20040 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
20050 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
20060 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
20070 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
20080 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
20090 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
200a0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
200b0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
200c0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
200d0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
200e0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
200f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
20100 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d  :.**.** {F13761}
20110 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
20120 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
20130 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
20140 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
20150 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
20160 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
20170 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
20180 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ning the.**     
20190 20 20 20 20 20 20 74 68 65 20 64 65 63 6c 61 72        the declar
201a0 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
201b0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
201c0 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
201d0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
201e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
201f0 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
20200 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20210 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
20220 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
20230 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
20240 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75  * {F13762}  A su
20250 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
20260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20270 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
20280 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
20290 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
202a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
202b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
202c0 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  r string.**     
202d0 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67        containing
202e0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61   the declared da
202f0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  tatype of the ta
20300 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
20310 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20  appears.**      
20320 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20       as the Nth 
20330 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64  column (numbered
20340 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
20350 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
20360 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
20370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20380 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nt] S..**.** {F1
20390 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c  3763}  If N is l
203a0 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20  ess than 0 or N 
203b0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
203c0 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20  or equal to.**  
203d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d           the num
203e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
203f0 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
20400 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
20410 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20        or if the 
20420 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
20430 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
20440 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74   or subquery rat
20450 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
20460 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f   than a table co
20470 6c 75 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d  lumn or if a mem
20480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
20490 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20  ailure.**       
204a0 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e      occurs durin
204b0 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65  g encoding conve
204c0 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20  rsions, then.** 
204d0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20            calls 
204e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
204f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
20500 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
20510 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
20520 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
20530 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  )] return NULL..
20540 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20560 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
20570 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20580 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20590 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
205a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
205b0 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
205c0 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
205d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
205e0 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13200}.**.**
205f0 20 41 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61   After an [prepa
20600 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
20610 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
20620 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20   with a call.** 
20630 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  to either [sqlit
20640 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
20660 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
20670 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  to one of.** the
20680 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20690 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
206a0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
206b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
206c0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75  .** then this fu
206d0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63  nction must be c
206e0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
206f0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
20700 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74  ate the .** stat
20710 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
20720 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
20730 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
20740 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20750 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
20760 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
20770 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
20780 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
20790 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
207a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
207b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
207c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
207d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
207e0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
207f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
20800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20810 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
20820 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
20830 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
20840 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
20850 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
20860 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
20870 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
20880 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
20890 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
208a0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
208b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
208c0 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61  e lagacy interfa
208d0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
208e0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
208f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
20900 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ], .** [SQLITE_D
20910 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
20920 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
20930 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
20940 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
20950 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
20960 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
20970 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  ther [SQLITE_OK 
20980 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  | result code].*
20990 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
209a0 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
209b0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
209c0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
209d0 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a  d as.** well..**
209e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
209f0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20a00 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
20a10 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
20a20 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
20a30 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
20a40 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
20a50 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
20a60 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d  tement is a COMM
20a70 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  IT.** or occurs 
20a80 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
20a90 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
20aa0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
20ab0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
20ac0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
20ad0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
20ae0 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f  t a COMMIT and o
20af0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
20b00 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
20b10 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
20b20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
20b30 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
20b40 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
20b50 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
20b60 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
20b70 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
20b80 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
20b90 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
20ba0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
20bb0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
20bc0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
20bd0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
20be0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
20bf0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
20c00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
20c10 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
20c20 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
20c30 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
20c40 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
20c50 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
20c60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
20c70 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
20c80 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
20c90 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  then .** [SQLITE
20ca0 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65  _ROW] is returne
20cb0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
20cc0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
20cd0 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72   ready.** for pr
20ce0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20  ocessing by the 
20cf0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
20d00 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
20d10 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
20d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20d30 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63  int | column acc
20d40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
20d50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
20d60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
20d70 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
20d80 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
20d90 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49  ta..** .** [SQLI
20da0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
20db0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
20dc0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
20dd0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
20de0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
20df0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
20e00 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
20e10 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
20e20 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
20e30 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
20e40 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
20e50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
20e60 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
20e70 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
20e80 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
20e90 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
20ea0 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
20eb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
20ec0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
20ed0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
20ee0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
20ef0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
20f00 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
20f10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
20f20 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
20f30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20f40 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
20f50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
20f60 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
20f70 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
20f80 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
20f90 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
20fa0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
20fb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
20fc0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
20fd0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
20fe0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
20ff0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
21000 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
21010 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
21020 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
21030 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
21040 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
21050 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
21060 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
21070 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75   had .** previou
21080 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
21090 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
210a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
210b0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
210c0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
210d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
210e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
210f0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
21100 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
21110 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
21120 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
21130 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
21140 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
21150 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  /b>.** In the le
21160 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
21170 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
21180 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79  step() API alway
21190 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
211a0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a  ric error code,.
211b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
211c0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
211d0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
211e0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
211f0 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  ** and [SQLITE_M
21200 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
21210 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
21220 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
21230 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21240 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
21250 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20  find one of the 
21260 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72  specific.** [err
21270 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
21280 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
21290 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
212a0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
212b0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
212c0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
212d0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
212e0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
212f0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
21300 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
21310 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
21320 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
21330 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
21340 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21350 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21360 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
21370 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
21380 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
21390 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
213a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
213b0 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d  , then the .** m
213c0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
213d0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
213e0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
213f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
21400 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
21410 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
21420 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
21430 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
21440 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
21450 31 33 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70  13202}  If [prep
21460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21470 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
21480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 75  .**           ru
21490 6e 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  n, then [sqlite3
214a0 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
214b0 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
214c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
214d0 20 20 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f          until to
214e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75   completion or u
214f0 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79  ntil it is ready
21500 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
21510 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
21520 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
21530 74 20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65  t set or an inte
21540 72 72 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d  rrupt or run-tim
21550 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
21560 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20  **.** {F15304}  
21570 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
21580 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21590 20 63 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20   causes the .** 
215a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
215b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
215c0 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c   to run to compl
215d0 65 74 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20  etion,.**       
215e0 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
215f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21600 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
21610 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
21620 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21630 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
21640 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
21650 64 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  dy.**           
21660 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65  to return anothe
21670 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
21680 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
21690 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
216a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a   [SQLITE_ROW]..*
216b0 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49  *.** {F15308}  I
216c0 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
216d0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e  ite3_step(S)] en
216e0 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20  counters an.**  
216f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21700 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65  3_interrupt|inte
21710 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
21720 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
21730 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
21740 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 61 69  rns an approprai
21750 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
21760 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
21770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
21780 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
21790 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
217a0 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
217b0 20 7b 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {F15310}  If an
217c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
217d0 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f  upt|interrupt] o
217e0 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
217f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
21800 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61  curs during a ca
21810 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21820 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  tep(S)].**      
21830 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70       for a [prep
21840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21850 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  S created using.
21860 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67  **           leg
21870 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
21880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21890 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
218a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
218b0 61 72 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68  are16()] then th
218c0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
218d0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
218e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
218f0 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  RROR], [SQLITE_B
21900 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  USY], or [SQLITE
21910 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74  _MISUSE]..*/.int
21920 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
21930 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21950 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
21960 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
21970 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F13770}.**.** 
21980 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
21990 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
219a0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
219b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
219c0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
219d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37  TS:.**.** {F1377
219e0 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
219f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
21a00 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
21a10 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ns.**           
21a20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
21a30 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
21a40 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
21a50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77  e.**           w
21a60 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
21a70 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
21a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
21a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
21aa0 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
21ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d  ..**.** {F13772}
21ac0 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
21ad0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
21ae0 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
21af0 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
21b00 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
21b10 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
21b20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21b30 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20  ] has been .**  
21b40 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20           called 
21b50 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
21b60 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a   statement] for.
21b70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
21b80 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63   first time sinc
21b90 65 20 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65  e it was [sqlite
21ba0 33 5f 70 72 65 70 61 72 65 7c 70 72 65 70 61 72  3_prepare|prepar
21bb0 65 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed].**          
21bc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
21bd0 65 74 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b  et|reset], the [
21be0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
21bf0 6e 74 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  nt(S)].**       
21c00 20 20 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75      routine retu
21c10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
21c20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
21c30 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21c40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
21c50 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
21c60 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
21c70 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59   {F10265}.** KEY
21c80 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
21c90 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36  XT.**.** {F10266
21ca0 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  }Every value in 
21cb0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
21cc0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
21cd0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
21ce0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
21cf0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21d00 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
21d10 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
21d20 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
21d30 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
21d40 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
21d50 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
21d60 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
21d70 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
21d80 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
21d90 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
21da0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
21db0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
21dc0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
21dd0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
21de0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
21df0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
21e00 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
21e10 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
21e20 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
21e30 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
21e40 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
21e50 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
21e60 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
21e70 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
21e80 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
21e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
21ea0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
21eb0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
21ec0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
21ed0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
21ee0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
21ef0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
21f00 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
21f10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
21f20 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
21f30 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
21f40 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
21f50 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
21f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21f70 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
21f80 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31  From A Query {F1
21f90 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3800}.**.** Thes
21fa0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
21fb0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
21fc0 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
21fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
21fe0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
21ff0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a  formation about.
22000 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ** a single colu
22010 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
22020 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  t result row of 
22030 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
22040 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66  ry.** case the f
22050 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
22060 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22070 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
22080 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
22090 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
220a0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
220b0 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
220c0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
220d0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
220e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
220f0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
22100 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
22110 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
22120 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
22130 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
22140 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
22150 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
22160 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
22170 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
22180 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22190 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
221a0 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
221b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
221c0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
221d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
221e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
221f0 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
22200 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
22210 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
22220 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
22230 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
22240 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
22250 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
22260 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
22270 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
22280 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
22290 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
222a0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
222b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
222c0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
222d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
222e0 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
222f0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
22300 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
22310 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
22320 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
22330 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
22340 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22350 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
22360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
22370 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
22380 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
22390 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
223a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
223b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
223c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
223d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
223e0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
223f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
22400 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
22410 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
22420 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
22430 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
22440 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
22450 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
22460 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
22470 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
22480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22490 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
224a0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
224b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
224c0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
224d0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
224e0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
224f0 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
22500 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
22510 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
22520 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
22530 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
22540 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
22550 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
22560 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
22570 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
22580 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22590 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
225a0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
225b0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
225c0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
225d0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
225e0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
225f0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
22600 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
22610 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
22620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22630 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
22640 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
22650 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22660 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
22670 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
22680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22690 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
226a0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
226b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
226c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
226d0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
226e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
226f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
22700 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
22710 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
22720 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
22730 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
22740 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
22750 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
22760 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
22770 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22780 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
22790 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
227a0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
227b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
227c0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
227d0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
227e0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
227f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22800 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
22810 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
22820 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
22830 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
22840 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
22850 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
22860 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
22870 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
22880 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
22890 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
228a0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
228b0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
228c0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
228d0 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
228e0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
228f0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
22900 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
22910 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
22920 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
22930 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
22940 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
22950 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
22960 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
22970 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22980 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
22990 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
229a0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
229b0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
229c0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
229d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
229e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
229f0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
22a00 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69   blob is an arbi
22a10 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
22a20 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
22a30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22a40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22a50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22a60 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
22a70 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
22a80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
22a90 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
22aa0 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
22ab0 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
22ac0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
22ad0 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54  of UTF-8.  .** T
22ae0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
22af0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
22b00 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
22b10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
22b20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
22b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
22b40 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
22b50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22b60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22b70 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
22b80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22b90 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
22ba0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
22bb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
22bc0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
22bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
22be0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
22bf0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
22c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22c10 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
22c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
22c30 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
22c40 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
22c50 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
22c60 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
22c70 74 69 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b  tines like .** [
22c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
22c90 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
22ca0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
22cb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22cc0 62 79 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65  bytes()],.** the
22cd0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
22ce0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
22cf0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22d00 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
22d10 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
22d20 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
22d30 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
22d40 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
22d50 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
22d60 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
22d70 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
22d80 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
22d90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
22da0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
22db0 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20  nally to do the 
22dc0 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75  conversion.** au
22dd0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
22de0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
22df0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
22e00 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a  nversions that.*
22e10 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  * are applied:.*
22e20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
22e30 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
22e40 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
22e50 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
22e60 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
22e70 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
22e80 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
22e90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
22ea0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
22eb0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
22ec0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
22ed0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
22ee0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
22ef0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
22f00 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22f10 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
22f20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
22f30 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
22f40 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22f50 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
22f60 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
22f70 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
22f80 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
22f90 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
22fa0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
22fb0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
22fc0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
22fd0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
22fe0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
22ff0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
23000 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
23010 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
23020 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23030 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20  td> Same as for 
23040 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
23050 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
23060 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23070 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
23080 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
23090 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
230a0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
230b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
230c0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
230d0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
230e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
230f0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23100 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
23110 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
23120 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
23130 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23140 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
23150 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
23160 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
23170 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
23180 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
23190 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
231a0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
231b0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
231c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
231d0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
231e0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
231f0 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
23200 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
23210 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
23220 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
23230 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
23240 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
23250 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
23260 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
23270 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
23280 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
23290 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
232a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
232b0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
232c0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
232d0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
232e0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
232f0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
23300 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
23310 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
23320 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
23330 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
23340 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74  ** on equavalent
23350 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
23360 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
23370 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
23380 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
23390 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
233a0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
233b0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
233c0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
233d0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
233e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
233f0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
23400 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
23410 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
23420 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
23430 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
23440 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
23450 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
23460 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
23470 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23480 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
23490 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63  ated. .** Type c
234a0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
234b0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
234c0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
234d0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
234e0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
234f0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70  * <ul>.** <li><p
23500 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
23510 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
23520 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
23530 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20  umn_text() .**  
23540 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74          or sqlit
23550 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23560 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
23570 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
23580 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20   might.**       
23590 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
235a0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
235b0 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  g.</p></li>.**.*
235c0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
235d0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
235e0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
235f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23600 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
23610 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
23620 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23630 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
23640 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
23650 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
23660 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36         to UTF-16
23670 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  .</p></li>.**.**
23680 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
23690 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
236a0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
236b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
236c0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
236d0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
236e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
236f0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
23700 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
23710 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
23720 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e     to UTF-8.</p>
23730 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
23740 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
23750 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
23760 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
23770 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
23780 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
23790 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
237a0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
237b0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
237c0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
237d0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
237e0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
237f0 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
23800 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
23810 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
23820 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
23830 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
23840 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
23850 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
23860 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69  ut sometime it i
23870 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
23880 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
23890 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
238a0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
238b0 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ted.  .**.** The
238c0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
238d0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
238e0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
238f0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
23900 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
23910 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
23920 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a  ys:.**.**  <ul>.
23930 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
23940 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
23950 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
23960 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23970 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
23980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23990 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
239a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
239b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
239c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
239d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
239e0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
239f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23a00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a  </li>.**  </ul>.
23a10 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
23a20 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
23a30 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
23a40 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c  lumn_text(), sql
23a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23a60 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  (),.** or sqlite
23a70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23a80 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
23a90 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
23aa0 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20   the desired.** 
23ab0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
23ac0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
23ad0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71  mn_bytes() or sq
23ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23af0 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e  es16() to.** fin
23b00 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
23b10 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
23b20 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71  t mix call to sq
23b30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23b40 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  t() or.** sqlite
23b50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
23b60 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
23b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23b80 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20  es16().  And do 
23b90 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73  not.** mix calls
23ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
23bb0 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 68  mn_text16() with
23bc0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23bd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
23bf0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
23c00 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
23c10 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
23c20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
23c30 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
23c40 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
23c50 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
23c60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
23c70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
23c80 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
23c90 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73  d.  The memory s
23ca0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
23cb0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
23cc0 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20   blobs is freed 
23cd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
23ce0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
23cf0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
23d00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
23d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23d20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
23d30 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
23d40 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c  c. into .** [sql
23d50 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
23d60 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
23d70 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
23d80 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
23d90 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
23da0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
23db0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
23dc0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
23dd0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
23de0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
23df0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
23e00 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
23e10 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
23e20 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
23e30 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
23e40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
23e50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
23e60 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
23e70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
23e80 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  M]..**.** INVARI
23e90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
23ea0 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
23eb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
23ec0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
23ed0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
23ee0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
23ef0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
23f00 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
23f10 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
23f20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
23f30 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
23f40 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68  to a blob and th
23f50 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
23f60 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
23f70 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
23f80 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
23f90 46 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c  F13806} The [sql
23fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23fb0 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  s(S,N)] interfac
23fc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
23fd0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
23fe0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
23ff0 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20   blob or string 
24000 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
24010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
24020 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
24030 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
24040 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
24050 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
24060 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
24070 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
24080 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
24090 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
240a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
240b0 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  text(S,N)]..**.*
240c0 2a 20 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b  * {F13809} The [
240d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
240e0 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74  ytes16(S,N)] int
240f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24100 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
24110 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
24120 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
24130 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
24140 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
24150 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
24160 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
24170 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
24180 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
24190 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
241a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
241b0 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e  mn_text16(S,N)].
241c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20  .**.** {F13812} 
241d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
241e0 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d  umn_double(S,N)]
241f0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
24200 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
24210 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
24220 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
24230 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
24240 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
24250 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24260 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
24270 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
24280 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
24290 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
242a0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
242b0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
242c0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
242d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
242e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
242f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
24300 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
24310 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
24320 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
24330 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
24340 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24350 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
24360 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
24370 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
24380 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
24390 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
243a0 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
243b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  er..**.** {F1381
243c0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
243d0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e  column_int64(S,N
243e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
243f0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
24400 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
24410 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24420 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
24430 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
24440 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
24450 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
24460 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
24470 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
24480 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
24490 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
244a0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
244b0 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71  {F13821} The [sq
244c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
244d0 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  t(S,N)] interfac
244e0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
244f0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24500 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
24510 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24520 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
24530 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24550 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
24560 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a  rminated UTF-8 .
24570 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
24580 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
24590 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
245a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
245b0 46 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c  F13824} The [sql
245c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
245d0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
245e0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
245f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24600 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24610 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24620 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24630 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24640 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24650 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
24660 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
24670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
24680 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
24690 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
246a0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
246b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
246c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
246d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
246e0 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  3827} The [sqlit
246f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53  e3_column_type(S
24700 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24710 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
24720 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54     one of [SQLIT
24730 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_NULL], [SQLITE
24740 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
24750 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20  TE_FLOAT],.**   
24760 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
24770 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  EXT], or [SQLITE
24780 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
24790 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20  riate for.**    
247a0 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f        the Nth co
247b0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
247c0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
247d0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
247e0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
247f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24800 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d  ..**.** {F13830}
24810 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24820 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
24830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24840 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
24850 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
24860 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24870 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24880 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
24890 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
248a0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
248b0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
248c0 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
248d0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
248e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
248f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24910 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24920 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24940 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
24950 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24960 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24970 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
24980 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24990 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
249a0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
249b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
249c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
249d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
249e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
249f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
24a00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
24a10 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
24a20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24a30 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
24a40 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
24a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24a60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24a70 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
24a80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
24a90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
24aa0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24ab0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
24ad0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24ae0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
24af0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
24b00 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
24b10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24b20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
24b30 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
24b40 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24b50 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33  ment Object {F13
24b60 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  300}.**.** The s
24b70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24b80 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
24b90 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
24ba0 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
24bb0 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68  tatement]. If th
24bc0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  e statement was.
24bd0 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63  ** executed succ
24be0 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74  essfully, or not
24bf0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
24c00 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b  , then SQLITE_OK
24c10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24c20 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
24c30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
24c40 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a  ailed then an .*
24c50 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
24c60 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
24c70 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
24c80 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  turned. .**.** T
24c90 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
24ca0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
24cb0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
24cc0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
24cd0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24ce0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
24cf0 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
24d00 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  ine has not .** 
24d10 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
24d20 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
24d30 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
24d40 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
24d50 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
24d60 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74   error or an int
24d70 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73  errupt.  (See [s
24d80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
24d90 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70  ()].) .** Incomp
24da0 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
24db0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
24dc0 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
24dd0 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a   cancelled,  .**
24de0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
24df0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
24e00 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72   and the .** [er
24e10 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
24e20 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
24e30 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
24e40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
24e50 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20  ** {F11302} The 
24e60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24e70 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
24e80 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20  destroys the.** 
24e90 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
24ea0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24eb0 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c  and releases all
24ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
24ed0 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73  ory and file res
24ee0 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74  ources held by t
24ef0 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  hat object..**.*
24f00 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68  * {F11304} If th
24f10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
24f20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
24f30 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
24f40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24f50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24f60 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65   S returned an e
24f70 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
24f80 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
24f90 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74  finalize(S)] ret
24fa0 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65  urns that same e
24fb0 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
24fc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
24fd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
24fe0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24ff0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
25000 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25010 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a  Object {F13330}.
25020 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25030 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
25040 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
25050 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65  reset a .** [pre
25060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25070 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b   object..** back
25080 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
25090 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
250a0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
250b0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
250c0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
250d0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
250e0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
250f0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
25100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
25110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
25120 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
25130 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
25140 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
25150 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
25160 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
25170 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32  s..**.** {F11332
25180 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
25190 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
251a0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
251b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
251c0 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
251d0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
251e0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
251f0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ogram..**.** {F1
25200 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73  1334} If the mos
25210 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
25220 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25230 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20  )] for .**      
25240 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
25250 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
25260 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
25270 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
25280 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
25290 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
252a0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
252b0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
252c0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
252d0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
252e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
252f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
25300 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36  ]..**.** {F11336
25310 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
25320 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25330 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
25340 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
25350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25360 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
25370 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
25380 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25390 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
253a0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
253b0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
253c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38  ]..**.** {F11338
253d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
253e0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
253f0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
25400 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
25410 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
25420 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25430 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
25440 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25450 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
25460 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
25470 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25480 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25490 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
254a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
254b0 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a  tions {F16100}.*
254c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
254d0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
254e0 6f 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20  outines} .**.** 
254f0 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69  These two functi
25500 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
25510 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66  y known as.** "f
25520 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
25530 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65 20   routines") are 
25540 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
25550 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25560 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f  regates.** or to
25570 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
25580 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69  havior of existi
25590 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
255a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
255b0 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e   The.** differen
255c0 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20  ce only between 
255d0 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20  the two is that 
255e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
255f0 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d  eter, the.** nam
25600 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
25610 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  ) function or ag
25620 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f  gregate, is enco
25630 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72  ded in UTF-8 for
25640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
25650 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
25660 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c  d UTF-16 for sql
25670 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25680 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
25690 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
256a0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
256b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
256c0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
256d0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
256e0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49   to be added.  I
256f0 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72  f a single.** pr
25700 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
25710 74 68 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61  than one [databa
25720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
25730 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
25740 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
25750 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
25760 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65  ndividually to e
25770 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
25780 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
25790 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
257a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
257b0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
257c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
257d0 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69  ted.** or redefi
257e0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67  ned..** The leng
257f0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
25800 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
25810 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
25820 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72  e of the .** zer
25830 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
25840 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
25850 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
25860 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
25870 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
25880 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
25890 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
258a0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
258b0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
258c0 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f  lt in an SQLITE_
258d0 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a  ERROR error..**.
258e0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
258f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75  ameter is the nu
25900 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25910 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
25920 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
25930 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
25940 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
25950 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
25960 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
25970 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
25980 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
25990 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
259a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
259b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
259c0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
259d0 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b  ifies what .** [
259e0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
259f0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
25a00 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
25a10 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
25a20 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
25a30 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
25a40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
25a50 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
25a60 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
25a70 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
25a80 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
25a90 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
25aa0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
25ab0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
25ac0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
25ad0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
25ae0 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
25af0 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
25b00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25b10 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
25b20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25b30 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
25b40 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
25b50 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
25b60 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
25b70 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
25b80 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
25b90 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
25ba0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
25bb0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
25bc0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
25bd0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
25be0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
25bf0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
25c00 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
25c10 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
25c20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
25c30 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
25c40 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
25c50 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
25c60 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  t.** text encodi
25c70 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
25c80 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
25c90 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ment should be.*
25ca0 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  * [SQLITE_ANY]..
25cb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
25cc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
25cd0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
25ce0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
25cf0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
25d00 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
25d10 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
25d20 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a  s pointer using.
25d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ** [sqlite3_user
25d40 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
25d50 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
25d60 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
25d70 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
25d80 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
25d90 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
25da0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
25db0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25dc0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
25dd0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72  L.** function or
25de0 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
25df0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
25e00 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
25e10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a  plementation of.
25e20 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c  ** the xFunc cal
25e30 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
25e40 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
25e50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
25e60 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  e xStep.** and x
25e70 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  Final parameters
25e80 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
25e90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
25ea0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
25eb0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74  tation.** of xSt
25ec0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ep and xFinal an
25ed0 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
25ee0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
25ef0 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a  c. To delete an.
25f00 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  ** existing SQL 
25f10 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
25f20 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
25f30 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
25f40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
25f50 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ack..**.** It is
25f60 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
25f70 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
25f80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
25f90 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
25fa0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
25fb0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
25fc0 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
25fd0 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
25fe0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
25ff0 20 64 69 66 66 65 72 69 6e 67 20 70 65 72 66 65   differing perfe
26000 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
26010 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
26020 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
26030 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
26040 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
26050 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
26060 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
26070 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
26080 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
26090 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20  .**.** {F16103} 
260a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
260b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
260c0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
260d0 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
260e0 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
260f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26100 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
26110 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
26120 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
26130 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
26140 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
26150 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20  gument as.**    
26160 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
26170 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
26180 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
26190 6e 73 74 65 61 64 20 6f 66 20 61 73 20 61 0a 2a  nstead of as a.*
261a0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
261b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
261c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d  ..**.** {F16106}
261d0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
261e0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  vocation of.**  
261f0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
26200 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26210 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
26220 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
26230 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  isters.**       
26240 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
26250 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
26260 73 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s in [database c
26270 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
26280 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f           used to
26290 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
262a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
262b0 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d  d X with N param
262c0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
262d0 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70    and having a p
262e0 65 72 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  erferred text en
262f0 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a  coding of E..**.
26300 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20 73 75  ** {F16109} A su
26310 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
26320 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26330 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26340 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
26350 20 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73          replaces
26360 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e   the P, F, S, an
26370 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  d L values from 
26380 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
26390 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
263a0 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20   the same D, X, 
263b0 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e  N, and E values.
263c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20  .**.** {F16112} 
263d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
263e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
263f0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
26400 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20   fails with.**  
26410 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
26420 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
26430 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53  _ERROR] if the S
26440 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
26450 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   X is.**        
26460 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35    longer than 25
26470 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76  5 bytes exclusiv
26480 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65  e of the zero te
26490 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
264a0 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65 72 20  {F16118} Either 
264b0 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61  F must be NULL a
264c0 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
264d0 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  on-NULL or else 
264e0 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  F.**          is
264f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20   non-NULL and S 
26500 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20  and L are NULL, 
26510 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20  otherwise.**    
26520 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
26530 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26540 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
26550 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
26560 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _ERROR]..**.** {
26570 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  F16121} The [sql
26580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26590 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  tion(D,...)] int
265a0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
265b0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
265c0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
265d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20  SQLITE_BUSY] if 
265e0 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65  there exist [pre
265f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
26600 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
26610 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
26620 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26630 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
26640 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20 5b 73   {F16124} The [s
26650 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26660 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
26670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
26680 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
26690 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
266a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
266b0 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72  OR] if parameter
266c0 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74   N (specifying t
266d0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
266e0 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e        of argumen
266f0 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
26700 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67  nction being reg
26710 69 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73  istered) is less
26720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
26730 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
26740 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20  than 127..**.** 
26750 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20  {F16127} When N 
26760 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
26770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
26780 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
26790 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
267a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
267b0 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73  causes callbacks
267c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66   to be invoked f
267d0 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
267e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
267f0 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65  named X when the
26800 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
26810 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
26820 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  function is.**  
26830 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20          exactly 
26840 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30  N..**.** {F16130
26850 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20  } When N is -1, 
26860 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
26870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
26880 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
26890 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
268a0 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
268b0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
268c0 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
268d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
268e0 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20  amed X with any 
268f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
26900 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  nts..**.** {F161
26910 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  33} When calls t
26920 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
26930 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
26940 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
26950 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
26960 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
26970 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
26980 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20  function X.**   
26990 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20         and when 
269a0 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  one implementati
269b0 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20  on has N>=0 and 
269c0 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d  the other has N=
269d0 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  (-1).**         
269e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
269f0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ion with a non-z
26a00 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72  ero N is preferr
26a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33  ed..**.** {F1613
26a20 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  6} When calls to
26a30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26a40 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26a50 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  E,...)].**      
26a60 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74      specify mult
26a70 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
26a80 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
26a90 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
26aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26ab0 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20   same number of 
26ac0 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20  arguments N but 
26ad0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a  with different.*
26ae0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
26af0 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65  ings E, then the
26b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26b10 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20  where E matches 
26b20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26b30 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
26b40 67 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a  g is preferred..
26b50 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46  **.** {F16139} F
26b60 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  or an aggregate 
26b70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65  SQL function cre
26b80 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
26b90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26ba0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26bb0 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29  D,X,N,E,P,0,S,L)
26bc0 5d 20 74 68 65 20 66 69 6e 69 61 6c 69 7a 65 72  ] the finializer
26bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
26be0 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77  ction L will alw
26bf0 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  ays be invoked e
26c00 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74  xactly once if t
26c10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  he.**          s
26c20 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69  tep function S i
26c30 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  s called one or 
26c40 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a  more times..**.*
26c50 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20  * {F16142} When 
26c60 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65  SQLite invokes e
26c70 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20  ither the xFunc 
26c80 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f  or xStep functio
26c90 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  n of.**         
26ca0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
26cb0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26cc0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
26cd0 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20  e created.**    
26ce0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
26cf0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26d00 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
26d10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26d20 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
26d30 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61     then the arra
26d40 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  y of [sqlite3_va
26d50 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73  lue] objects pas
26d60 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20  sed as the.**   
26d70 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72         third par
26d80 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 79  ameter are alway
26d90 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  s [protected sql
26da0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26db0 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  cts..*/.int sqli
26dc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26dd0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
26de0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
26df0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26e00 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26e10 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26e20 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26e30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
26e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26e60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
26e70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26e80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26e90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26ea0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26eb0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
26ec0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26ed0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
26ee0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
26ef0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
26f00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
26f10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
26f20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
26f30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
26f40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
26f50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
26f60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
26f70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
26f80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26fa0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
26fb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
26fc0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
26fd0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
26fe0 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d  codings {F10267}
26ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
27000 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
27010 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
27020 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
27030 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
27040 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
27050 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
27060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27070 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
27080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
27090 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
270a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
270b0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
270c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
270d0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
270e0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
270f0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
27100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
27110 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
27120 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
27130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
27140 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
27150 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
27160 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
27170 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27180 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
27190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73  ** CAPI3REF: Obs
271a0 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a  olete Functions.
271b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
271c0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f  tions are all no
271d0 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20  w obsolete.  In 
271e0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
271f0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
27200 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
27210 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65  h older code, we
27220 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70   continue to sup
27230 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75  port.** these fu
27240 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65  nctions.  Howeve
27250 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65  r, new developme
27260 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75  nt projects shou
27270 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
27280 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
27290 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
272a0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
272b0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
272c0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
272d0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
272e0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
272f0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
27300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
27310 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
27320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27330 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
27340 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
27350 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
27360 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
27370 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
27380 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
27390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
273a0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
273b0 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
273c0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
273d0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
273e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
273f0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
27400 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
27410 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
27420 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
27430 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
27440 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
27450 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
27460 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F15100}.**.** 
27470 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
27480 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
27490 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
274a0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
274b0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
274c0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
274d0 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
274e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
274f0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
27500 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
27510 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
27520 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
27530 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
27540 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
27550 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
27560 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
27570 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
27580 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27590 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
275a0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
275b0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
275c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
275d0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
275e0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
275f0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
27600 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
27610 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
27620 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
27630 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27640 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27650 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
27660 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27670 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
27680 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
27690 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
276a0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
276b0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
276c0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
276d0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
276e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
276f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
27700 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
27710 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
27720 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27730 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
27740 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
27750 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
27760 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
27770 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27780 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
27790 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
277a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
277b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
277c0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
277d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
277e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
277f0 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  umn_blob | sqlit
27800 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74  e3_column_* rout
27810 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68 61  ines] except tha
27820 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  t .** these rout
27830 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
27840 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
27850 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27860 65 63 74 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69  ect pointer.** i
27870 6e 73 74 65 61 64 20 6f 66 20 61 6e 20 5b 73 71  nstead of an [sq
27880 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
27890 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
278a0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
278b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
278c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
278d0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
278e0 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20 73  tracts a UTF16 s
278f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
27900 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
27910 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
27920 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
27930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27940 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
27950 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27960 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
27970 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31 36  ** extract UTF16
27980 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
27990 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
279a0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
279b0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
279c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
279d0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
279e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
279f0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
27a00 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
27a10 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
27a20 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
27a30 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
27a40 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
27a50 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
27a60 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
27a70 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
27a80 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
27a90 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
27aa0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
27ab0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
27ac0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20  her.** words if 
27ad0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
27ae0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
27af0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
27b00 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
27b10 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20  ersion is done. 
27b20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
27b30 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
27b40 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54    The .** [SQLIT
27b50 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
27b60 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
27b70 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
27b80 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  ed..**.** Please
27b90 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
27ba0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
27bb0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
27bc0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ointer that.** i
27bd0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
27be0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27bf0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27c00 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
27c10 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
27c20 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
27c30 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
27c40 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
27c50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
27c60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27c70 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
27c80 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
27c90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27ca0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
27cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27cc0 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  xt16()].  .**.**
27cd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27ce0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27cf0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27d00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
27d10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
27d20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27d30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27d40 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a  rameters..**.**.
27d50 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
27d60 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54 68  *.** {F15103} Th
27d70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27d80 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
27d90 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
27da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
27db0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27dc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
27dd0 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20  into a blob and 
27de0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a  then returns a.*
27df0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
27e00 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
27e10 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
27e20 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {F15106} The [s
27e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27e40 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
27e50 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
27e60 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
27e70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27e80 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28  blob or string (
27e90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
27ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
27eb0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
27ec0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
27ed0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
27ee0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27ef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
27f00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
27f10 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
27f20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
27f30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27f40 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
27f50 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
27f60 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
27f70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27f80 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
27f90 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
27fa0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
27fb0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
27fc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27fd0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
27fe0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
27ff0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
28000 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
28010 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
28020 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28030 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
28040 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
28050 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28060 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
28070 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28080 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
28090 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20  ** {F15112} The 
280a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
280b0 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
280c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
280d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
280e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
280f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
28100 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
28110 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
28120 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
28130 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
28140 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
28150 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {F15115} The [sq
28160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
28170 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
28180 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28190 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
281a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
281b0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
281c0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
281d0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
281e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
281f0 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
28200 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
28210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d  ..**.** {F15118}
28220 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28230 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
28240 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28250 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28260 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
28270 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28280 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
28290 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
282a0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
282b0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
282c0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
282d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20  .**.** {F15121} 
282e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
282f0 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
28300 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28310 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
28320 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28330 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28340 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
28350 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a  rminated UTF-8 .
28360 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
28370 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
28380 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28390 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
283a0 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F15124} The [sql
283b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
283c0 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
283d0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
283e0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
283f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28400 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28410 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28420 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
28430 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
28440 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
28450 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
28460 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
28470 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28480 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28490 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54  **.** {F15127} T
284a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
284b0 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
284c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
284d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
284e0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
284f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28500 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
28510 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
28520 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
28530 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
28540 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
28550 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
28560 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28570 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
28580 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d  ..**.** {F15130}
28590 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
285a0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
285b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
285c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
285d0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
285e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
285f0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
28600 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
28610 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
28620 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
28630 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
28640 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
28650 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
28660 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
28670 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
28680 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
28690 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
286a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
286b0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
286c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
286d0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
286e0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
286f0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
28700 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
28710 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
28720 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
28730 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
28740 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
28750 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
28760 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20  .**.** {F15136} 
28770 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28780 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
28790 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
287a0 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
287b0 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
287c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
287d0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
287e0 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
287f0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
28800 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
28810 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
28820 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
28830 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
28840 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
28850 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
28860 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
28870 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
28880 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
28890 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
288a0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
288b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
288c0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
288d0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
288e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
288f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28910 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
28920 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
28930 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
28940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28950 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
28960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28970 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
28980 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
28990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
289a0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
289b0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
289c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
289d0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
289e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
289f0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
28a00 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
28a10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28a20 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
28a30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28a40 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
28a50 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
28a60 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
28a70 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
28a80 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
28a90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
28aa0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
28ab0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28ac0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
28ad0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
28ae0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28af0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28b10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28b20 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
28b30 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28b40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
28b50 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
28b60 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
28b70 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
28b80 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
28b90 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36  ion Context {F16
28ba0 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  210}.**.** The i
28bb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28bc0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
28bd0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
28be0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
28bf0 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
28c00 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
28c10 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a   their state.  .
28c20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
28c30 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
28c40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28c50 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
28c60 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
28c70 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
28c80 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
28c90 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
28ca0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73   memory.** zeros
28cb0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
28cc0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28cd0 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e  ter to it..** On
28ce0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
28cf0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
28d00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28d10 65 5f 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66  e_context().** f
28d20 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
28d30 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
28d40 6e 64 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62  ndex, the same b
28d50 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
28d60 64 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  d..** The implem
28d70 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
28d80 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
28d90 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e 65   use the returne
28da0 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
28db0 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
28dc0 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  ** SQLite automa
28dd0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
28de0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66  e allocated buff
28df0 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  er when the aggr
28e00 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63  egate.** query c
28e10 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
28e20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28e30 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
28e40 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  copy of the .** 
28e50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
28e60 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
28e70 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
28e80 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
28e90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
28ea0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
28eb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
28ec0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
28ed0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
28ee0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
28ef0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
28f00 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
28f10 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
28f20 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
28f30 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
28f40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
28f50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
28f60 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20  6211} The first 
28f70 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
28f80 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
28f90 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
28fa0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
28fb0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
28fc0 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65  ance of an aggre
28fd0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66  gate function (f
28fe0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
28ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
29000 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51  ext C) causes SQ
29010 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  Lite to allocati
29020 6f 6e 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  on N bytes of me
29030 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20  mory,.**        
29040 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f    zero that memo
29050 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ry, and return a
29060 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29070 61 6c 6c 6f 63 61 74 69 6f 6e 65 64 0a 2a 2a 20  allocationed.** 
29080 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e           memory.
29090 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20  .**.** {F16213} 
290a0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
290b0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
290c0 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20  urs during.**   
290d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
290e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
290f0 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65  t(C,N)] then the
29100 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
29110 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  s 0..**.** {F162
29120 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73  15} Second and s
29130 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
29140 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20  tions of.**     
29150 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
29160 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29170 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61  C,N)] for the sa
29180 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  me context point
29190 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  er C.**         
291a0 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61   ignore the N pa
291b0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
291c0 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
291d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
291e0 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65       block of me
291f0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
29200 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63   the first invoc
29210 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ation..**.** {F1
29220 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79  6217} The memory
29230 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73   allocated by [s
29240 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29250 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69  _context(C,N)] i
29260 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  s.**          au
29270 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
29280 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61  d on the next ca
29290 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
292a0 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  eset()].**      
292b0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
292c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20  finalize()] for 
292d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
292e0 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e  atement] contain
292f0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
29300 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
29310 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
29320 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  d with context C
29330 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
29340 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29350 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
29360 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
29370 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
29380 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
29390 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  or Functions {F1
293a0 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6240}.**.** The 
293b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
293c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
293d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
293e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
293f0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
29400 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
29410 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
29420 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  er).** of the th
29430 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
29440 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
29450 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29460 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29470 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
29480 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
29490 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
294a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
294b0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
294c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
294d0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
294e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
294f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
29500 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
29510 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29520 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
29530 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
29540 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34  TS:.**.** {F1624
29550 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
29560 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e  user_data(C)] in
29570 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29580 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
29590 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e            P poin
295a0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
295b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
295c0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
295d0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
295e0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
295f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
29600 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
29610 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
29620 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
29630 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
29640 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
29650 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20   with .**       
29660 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74     [sqlite3_cont
29670 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  ext] C..*/.void 
29680 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
29690 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
296a0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
296b0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
296c0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
296d0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30  unctions {F16250
296e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
296f0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
29700 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
29710 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
29720 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
29730 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
29740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29750 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
29760 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  er).** of the th
29770 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
29780 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
29790 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
297a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
297b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
297c0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
297d0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
297e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
297f0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
29800 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29810 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65  .** {F16253} The
29820 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
29830 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20  t_db_handle(C)] 
29840 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29850 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
29860 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f  **          D po
29870 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
29880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29890 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
298a0 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
298b0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
298c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
298d0 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
298e0 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
298f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
29900 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
29910 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
29920 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20  ed with .**     
29930 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
29940 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c  ntext] C..*/.sql
29950 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
29960 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
29970 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29990 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
299a0 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31 36  iliary Data {F16
299b0 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  270}.**.** The f
299c0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
299d0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
299e0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
299f0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
29a00 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
29a10 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
29a20 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
29a30 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
29a40 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
29a50 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
29a60 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
29a70 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
29a80 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
29a90 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
29aa0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
29ab0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
29ac0 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70  ta-data may be p
29ad0 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
29ae0 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
29af0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
29b00 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
29b10 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
29b20 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
29b30 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
29b40 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
29b50 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
29b60 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
29b70 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73  .** meta-data as
29b80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
29b90 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
29ba0 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
29bb0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
29bc0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
29bd0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
29be0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
29bf0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
29c00 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
29c10 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
29c20 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
29c30 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
29c40 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
29c50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
29c60 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
29c70 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
29c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29c90 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
29ca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29cb0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29cc0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
29cd0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
29ce0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
29cf0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
29d00 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
29d10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
29d20 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
29d30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29d40 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20  ction..** If no 
29d50 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65  meta-data has be
29d60 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65 74  en ever been set
29d70 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20   for the Nth.** 
29d80 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29d90 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
29da0 74 68 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e  the coorespondin
29db0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
29dc0 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e  eter.** has chan
29dd0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
29de0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
29df0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
29e00 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72  t_auxdata().** r
29e10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
29e20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
29e30 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
29e40 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
29e50 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d   saves the meta-
29e60 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
29e70 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
29e80 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
29e90 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65  eta-data for the
29ea0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
29eb0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
29ec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29ed0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
29ee0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
29ef0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
29f00 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
29f10 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
29f20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
29f30 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a  en destroyed. .*
29f40 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
29f50 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
29f60 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
29f70 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74  ructor .** funct
29f80 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
29f90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
29fa0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
29fb0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
29fc0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e  e meta-data when
29fd0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
29fe0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
29ff0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
2a000 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
2a010 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
2a020 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
2a030 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
2a040 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
2a050 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
2a060 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
2a070 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a  p meta-data on.*
2a080 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72 20  * any parameter 
2a090 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2a0a0 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68  at any time.  Th
2a0b0 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
2a0c0 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65 20  .** is that the 
2a0d0 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
2a0e0 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
2a0f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
2a100 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a  .** dropped..**.
2a110 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20  ** In practice, 
2a120 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72 65  meta-data is pre
2a130 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2a140 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2a150 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2a160 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2a170 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2a180 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2a190 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2a1a0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69  ues and SQL vari
2a1b0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ables..**.** The
2a1c0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2a1d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2a1e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2a1f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2a200 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2a210 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2a220 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a230 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73   {F16272} The [s
2a240 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a250 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ta(C,N)] interfa
2a260 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a270 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
2a280 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   to metadata ass
2a290 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2a2a0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2a2b0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2a2c0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
2a2d0 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20  hose context is 
2a2e0 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  C, or NULL if th
2a2f0 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
2a300 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ta associated.**
2a310 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
2a320 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  hat parameter..*
2a330 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68  *.** {F16274} Th
2a340 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2a350 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2a360 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67   interface assig
2a370 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ns a metadata.**
2a380 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2a390 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70  r P to the Nth p
2a3a0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2a3b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  SQL function wit
2a3c0 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  h context.**    
2a3d0 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b        C..**.** {
2a3e0 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77  F16276} SQLite w
2a3f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2a400 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
2a410 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2a420 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
2a430 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61  hich is the meta
2a440 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66  data pointer P f
2a450 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
2a460 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
2a470 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a480 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68  ata(C,N,P,D)] wh
2a490 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  en SQLite ceases
2a4a0 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20   to hold.**     
2a4b0 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74       the metadat
2a4c0 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37  a..**.** {F16277
2a4d0 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20  } SQLite ceases 
2a4e0 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61  to hold metadata
2a4f0 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63   for an SQL func
2a500 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
2a510 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
2a520 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
2a530 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  t parameter chan
2a540 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ges..**.** {F162
2a550 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  78} When [sqlite
2a560 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2a570 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b  N,P,D)] is invok
2a580 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74  ed, the destruct
2a590 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
2a5a0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79  s called for any
2a5b0 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20   prior metadata 
2a5c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a5d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2a5e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  n.**          co
2a5f0 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61  ntext C and para
2a600 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  meter N..**.** {
2a610 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77  F16279} SQLite w
2a620 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63  ill call destruc
2a630 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74  tors for any met
2a640 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64  adata it is hold
2a650 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2a660 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2a670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a680 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68  ent] S when eith
2a690 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
2a6a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a6b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2a6c0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
2a6d0 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  lled..*/.void *s
2a6e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a6f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2a700 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
2a710 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
2a720 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2a730 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
2a740 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
2a750 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
2a760 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
2a770 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
2a780 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
2a790 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30  Behavior {F10280
2a7a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  }.**.** These ar
2a7b0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2a7c0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
2a7d0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
2a7e0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
2a7f0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
2a800 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2a810 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a820 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20  lob()].  If the 
2a830 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2a840 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2a850 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2a860 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2a870 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2a880 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2a890 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2a8a0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2a8b0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2a8c0 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c  ed.  The .** SQL
2a8d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2a8e0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2a8f0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2a900 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2a910 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2a920 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2a930 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2a940 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2a950 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2a960 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2a970 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2a980 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2a990 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2a9a0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2a9b0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2a9c0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2a9d0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2a9e0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2a9f0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2aa00 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2aa10 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2aa20 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2aa30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2aa40 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2aa50 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2aa60 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2aa70 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2aa80 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2aa90 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2aaa0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2aab0 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34  L Function {F164
2aac0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
2aad0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2aae0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
2aaf0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2ab00 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
2ab10 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
2ab20 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2ab30 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
2ab40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ab50 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2ab60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ab70 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
2ab80 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2ab90 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2aba0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
2abb0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
2abc0 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  e the .** [sqlit
2abd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2abe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66  qlite3_bind_*] f
2abf0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
2ac00 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69  ns used.** to bi
2ac10 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
2ac20 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
2ac30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ac40 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
2ac50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2ac60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2ac70 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75  ite3_bind_* docu
2ac80 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a  mentation] for.*
2ac90 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
2aca0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2acb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2acc0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2acd0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2ace0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2acf0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2ad00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ad10 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2ad20 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2ad30 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2ad40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ad50 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2ad60 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2ad70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2ad80 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a  ird parameter. .
2ad90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2ada0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
2adb0 20 69 6e 65 72 66 61 63 65 73 20 73 65 74 20 74   inerfaces set t
2adc0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2add0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ade0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2adf0 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
2ae00 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
2ae10 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
2ae20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
2ae30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
2ae40 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
2ae50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2ae60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ae70 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
2ae80 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2ae90 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2aea0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2aeb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2aec0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2aed0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2aee0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2aef0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2af00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2af10 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2af20 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2af30 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
2af40 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
2af50 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
2af60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
2af70 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
2af80 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  n..** SQLite use
2af90 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2afa0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2afb0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2afc0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2afd0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2afe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2aff0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2b000 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2b010 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74   message.  SQLit
2b020 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2b030 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2b040 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2b050 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b060 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20 53 51  or() as UTF8. SQ
2b070 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2b080 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2b090 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2b0a0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2b0b0 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  TF16 in native.*
2b0c0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
2b0d0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2b0e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b0f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2b100 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b110 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2b120 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2b130 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2b140 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2b150 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2b160 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2b170 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2b180 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
2b190 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b1a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b1b0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
2b1c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b1d0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
2b1e0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2b1f0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
2b200 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
2b210 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
2b220 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2b230 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
2b240 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
2b250 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b260 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2b270 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b280 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2b290 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76  make a copy priv
2b2a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2b2b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2b2c0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2b2d0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2b2e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2b2f0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2b300 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2b310 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2b320 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2b330 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
2b340 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b350 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2b360 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2b370 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2b380 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2b390 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2b3a0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2b3b0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
2b3c0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2b3d0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2b3e0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
2b3f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2b400 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2b410 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2b420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b430 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2b440 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2b450 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2b460 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b470 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
2b480 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2b490 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74  s SQLite.** to t
2b4a0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e  hrow an error in
2b4b0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2b4c0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
2b4d0 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20  s to long.** to 
2b4e0 72 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20  represent.  The 
2b4f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2b500 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2b510 0a 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74  .** causes SQLit
2b520 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  e to throw an ex
2b530 63 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69  ception indicati
2b540 6e 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a  ng that the a.**
2b550 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2b560 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
2b570 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b580 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2b590 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2b5a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2b5b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b5c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b5d0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2b5e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2b5f0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2b600 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2b610 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
2b620 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2b630 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2b640 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2b650 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2b660 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b670 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b680 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2b690 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2b6a0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2b6b0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2b6c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b6d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2b6e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2b6f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2b700 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2b710 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b720 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2b730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b740 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2b750 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2b760 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73  _text16(), .** s
2b770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2b780 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2b790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2b7a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2b7b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2b7c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2b7d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b7e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b7f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2b800 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2b810 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2b820 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2b830 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2b840 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2b850 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2b860 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2b870 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53  spectively..** S
2b880 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2b890 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2b8a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b8b0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2b8c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2b8d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b8e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2b8f0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  s..** If the 3rd
2b900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2b910 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b920 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2b930 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2b940 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2b950 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2b960 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2b970 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75  ameter .** throu
2b980 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2b990 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2b9a0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2b9b0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2b9c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2b9d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2b9e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2b9f0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2ba00 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2ba10 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2ba20 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2ba30 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2ba40 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2ba50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ba60 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2ba70 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
2ba80 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2ba90 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2baa0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2bab0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2bac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bad0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2bae0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2baf0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2bb00 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2bb10 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2bb20 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2bb30 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e  blob result when
2bb40 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2bb50 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2bb60 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2bb70 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2bb80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2bb90 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2bba0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2bbb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2bbc0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2bbd0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2bbe0 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53  TATIC, then.** S
2bbf0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2bc00 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  at the text or b
2bc10 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f  lob result is co
2bc20 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
2bc30 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70  .** does not cop
2bc40 79 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63  y the space or c
2bc50 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2bc60 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2bc70 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2bc80 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
2bc90 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2bca0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2bcb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2bcc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2bcd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bce0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2bcf0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2bd00 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2bd10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2bd20 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2bd30 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2bd40 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2bd50 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2bd60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2bd70 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2bd80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2bd90 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2bda0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2bdb0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2bdc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bdd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bde0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2bdf0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2be00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2be10 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2be20 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2be30 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
2be40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2be50 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2be60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2be70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2be80 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2be90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2bea0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
2beb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
2bec0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
2bed0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
2bee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bef0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
2bf00 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2bf10 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
2bf20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2bf30 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2bf40 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2bf50 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2bf60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2bf70 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2bf80 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2bf90 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2bfa0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2bfb0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2bfc0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2bfd0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2bfe0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2bff0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2c000 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2c010 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65  ead .** than the
2c020 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
2c030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c040 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c050 20 74 68 61 74 20 72 65 63 69 65 76 65 64 0a 2a   that recieved.*
2c060 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
2c070 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
2c080 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2c090 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c0a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c0b0 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65  .** {F16403} The
2c0c0 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
2c0d0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
2c0e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
2c0f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2c100 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
2c110 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2c120 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2c130 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2c140 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2c150 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2c160 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62  n C to be a blob
2c170 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73   that is N bytes
2c180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
2c190 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20  length and with 
2c1a0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20  content pointed 
2c1b0 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  to by V..**.** {
2c1c0 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c  F16409} The [sql
2c1d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2c1e0 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
2c1f0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2c200 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2c210 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2c220 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2c230 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2c240 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
2c250 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16412} The [sqli
2c260 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c270 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
2c280 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2c290 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2c2a0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
2c2b0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
2c2c0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
2c2d0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
2c2e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
2c2f0 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65  OR] and a UTF8 e
2c300 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70  rror message cop
2c310 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
2c320 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c330 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65   first zero byte
2c340 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2c350 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20  s are read if N 
2c360 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
2c370 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20  ** {F16415} The 
2c380 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c390 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20  error16(C,V,N)] 
2c3a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c3b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
2c3c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
2c3d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c3e0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c3f0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2c400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2c410 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
2c420 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79   UTF16 native by
2c430 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
2c440 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
2c450 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
2c460 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2c470 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c480 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2c490 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
2c4a0 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
2c4b0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2c4c0 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  F16418} The [sql
2c4d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c4e0 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
2c4f0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2c500 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
2c510 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
2c520 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
2c530 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
2c540 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
2c550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2c560 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
2c570 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c580 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2c590 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68  *.** {F16421} Th
2c5a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c5b0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
2c5c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2c5d0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
2c5e0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
2c5f0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2c600 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
2c610 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
2c620 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
2c630 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
2c640 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
2c650 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
2c660 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34  e..**.** {F16424
2c670 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c680 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2c690 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
2c6a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c6b0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c6c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
2c6d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2c6e0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2c6f0 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
2c700 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
2c710 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2c720 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
2c730 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68  *.** {F16427} Th
2c740 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c750 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
2c760 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c770 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2c780 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2c790 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2c7a0 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
2c7b0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
2c7c0 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {F16430} The [s
2c7d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2c7e0 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
2c7f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2c800 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2c810 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2c820 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2c830 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
2c840 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
2c850 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  F16433} The [sql
2c860 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
2c870 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
2c880 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2c890 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2c8a0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c8b0 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
2c8c0 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65  .** {F16436} The
2c8d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c8e0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
2c8f0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c900 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c910 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2c920 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c930 62 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69  be the UTF8 stri
2c940 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  ng.**          V
2c950 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2c960 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
2c970 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
2c980 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
2c990 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
2c9a0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2c9b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39  e..**.** {F16439
2c9c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c9d0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
2c9e0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2c9f0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2ca00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2ca10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2ca20 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2ca30 46 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  F16 native byte 
2ca40 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
2ca50 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
2ca60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2ca70 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
2ca80 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
2ca90 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2caa0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
2cab0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2cac0 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20  ** {F16442} The 
2cad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cae0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2caf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2cb00 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cb10 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2cb20 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cb30 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2cb40 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
2cb50 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
2cb60 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2cb70 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20  zero if N is.** 
2cb80 20 20 20 20 20 20 20 20 20 69 73 20 6e 65 67 61           is nega
2cb90 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2cba0 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
2cbb0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2cbc0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2cbd0 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
2cbe0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2cbf0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2cc00 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2cc10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2cc20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2cc30 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2cc40 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65  e UTF16 little-e
2cc50 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2cc60 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
2cc70 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2cc80 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
2cc90 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
2cca0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2ccb0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
2ccc0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2ccd0 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20  ** {F16448} The 
2cce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ccf0 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65  value(C,V)] inte
2cd00 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2cd10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2cd20 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2cd30 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b  nction C to be [
2cd40 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2cd50 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20  te3_value].**   
2cd60 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e         object V.
2cd70 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20  .**.** {F16451} 
2cd80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2cd90 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
2cda0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2cdb0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cdc0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2cdd0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cde0 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20  to be an N-byte 
2cdf0 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f  blob of all zero
2ce00 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34  s..**.** {F16454
2ce10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2ce20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61  esult_error()] a
2ce30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2ce40 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a  lt_error16()].**
2ce50 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2ce60 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79  aces make a copy
2ce70 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20   of their error 
2ce80 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
2ce90 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  before.**       
2cea0 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a     returning..**
2ceb0 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20  .** {F16457} If 
2cec0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
2ced0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2cee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2cef0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
2cf00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2cf10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
2cf20 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
2cf30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2cf40 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2cf50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2cf60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2cf70 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
2cf80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2cf90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2cfa0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
2cfb0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53   the constant [S
2cfc0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a  QLITE_STATIC].**
2cfd0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e            then n
2cfe0 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  o destructor is 
2cff0 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ever called on t
2d000 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64  he pointer V and
2d010 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
2d020 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74      assumes that
2d030 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e   V is immutable.
2d040 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20  .**.** {F16460} 
2d050 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
2d060 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
2d070 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d080 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
2d090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d0a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d0b0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
2d0c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d0d0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
2d0e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d0f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d100 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
2d110 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2d120 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d130 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
2d140 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
2d150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2d160 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
2d170 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
2d180 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ces makes a copy
2d190 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2d1a0 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56      content of V
2d1b0 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65   and retains the
2d1c0 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   copy..**.** {F1
2d1d0 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64  6463} If the D d
2d1e0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
2d1f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d200 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
2d210 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2d220 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d230 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
2d240 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
2d250 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
2d260 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2d270 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d280 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
2d290 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
2d2a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2d2b0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
2d2c0 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76  ,N,D)] is some v
2d2d0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
2d2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2d2f0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
2d300 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53  E_STATIC] and [S
2d310 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2d320 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20   then .**       
2d330 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69     SQLite will i
2d340 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2d350 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73  ctor D with V as
2d360 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
2d370 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
2d380 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2d390 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76  hed with the V v
2d3a0 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alue..*/.void sq
2d3b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2d3c0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2d3d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2d3e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2d3f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2d400 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2d410 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2d420 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
2d430 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d440 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
2d450 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2d460 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
2d470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d480 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
2d490 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d4a0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
2d4b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d4c0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
2d4d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d4e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d4f0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
2d500 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d510 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2d520 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
2d530 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
2d540 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2d550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2d560 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2d570 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2d580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2d590 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
2d5a0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
2d5b0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
2d5c0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2d5d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d5e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d5f0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
2d600 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d610 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
2d620 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d630 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d640 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
2d650 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d660 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d670 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d680 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d690 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2d6a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d6b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d6c0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2d6d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d6e0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
2d6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d700 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d710 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2d720 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d730 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
2d740 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2d750 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d760 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d770 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
2d780 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d790 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2d7a0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
2d7b0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
2d7c0 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a  uences {F16600}.
2d7d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2d7e0 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
2d7f0 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
2d800 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
2d810 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2d820 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66  *] handle specif
2d830 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2d840 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a   argument. .**.*
2d850 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
2d860 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2d870 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2d880 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2d890 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2d8a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d8b0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2d8c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d8d0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2d8e0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2d8f0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2d900 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2d910 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
2d920 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
2d930 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
2d940 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2d950 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2d960 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d970 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
2d980 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
2d990 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2d9a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2d9b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2d9c0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
2d9d0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
2d9e0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
2d9f0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
2da00 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
2da10 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
2da20 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
2da30 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2da40 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
2da50 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
2da60 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
2da70 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
2da80 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
2da90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2daa0 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
2dab0 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
2dac0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
2dad0 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
2dae0 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
2daf0 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
2db00 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
2db10 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
2db20 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
2db30 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
2db40 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
2db50 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
2db60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2db70 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
2db80 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
2db90 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
2dba0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
2dbb0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
2dbc0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
2dbd0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
2dbe0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
2dbf0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
2dc00 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
2dc10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
2dc20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2dc30 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2dc40 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
2dc50 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
2dc60 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61  .** the fourth a
2dc70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2dc80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dc90 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ion() or.** sqli
2dca0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2dcb0 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20  tion16() as its 
2dcc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
2dcd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
2dce0 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
2dcf0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
2dd00 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
2dd10 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
2dd20 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
2dd30 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
2dd40 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
2dd50 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
2dd60 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
2dd70 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
2dd80 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
2dd90 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
2dda0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2ddb0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
2ddc0 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61  red. {END} The a
2ddd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2dde0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75  ed collation rou
2ddf0 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  tine should.** r
2de00 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
2de10 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
2de20 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   if.** the first
2de30 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
2de40 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
2de50 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2de60 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74  the second.** st
2de70 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
2de80 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
2de90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2dea0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2deb0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2dec0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2ded0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2dee0 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20   excapt that it 
2def0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
2df00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2df10 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
2df20 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
2df30 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
2df40 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
2df50 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2df60 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
2df70 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
2df80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
2df90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
2dfa0 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
2dfb0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
2dfc0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2dfd0 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
2dfe0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
2dff0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
2e000 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
2e010 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
2e020 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
2e030 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
2e040 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
2e050 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
2e060 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
2e070 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
2e080 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
2e090 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2e0a0 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20  *.** {F16603} A 
2e0b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2e0c0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
2e0d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2e0e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2e0f0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
2e100 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
2e110 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
2e120 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
2e130 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e140 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
2e150 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
2e160 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
2e170 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e180 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
2e190 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
2e1a0 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
2e1b0 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ng E..**.** {F16
2e1c0 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
2e1d0 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
2e1e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
2e1f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2e200 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e210 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2e220 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
2e230 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
2e240 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
2e250 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
2e260 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
2e270 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
2e280 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
2e290 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
2e2a0 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
2e2b0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cters..**.** {F1
2e2c0 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
2e2d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2e2e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e2f0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2e300 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
2e310 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
2e320 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
2e330 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
2e340 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
2e350 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
2e360 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
2e370 46 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74  F16609} The dest
2e380 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
2e390 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e3a0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2e3b0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
2e3c0 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
2e3d0 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
2e3e0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
2e3f0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
2e400 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
2e410 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
2e420 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
2e430 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20  *.** {F16612} A 
2e440 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2e450 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
2e460 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
2e470 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ded..**.** {F166
2e480 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
2e490 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
2e4a0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
2e4b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e4c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2e4d0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
2e4e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
2e4f0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54  **.** {F16618} T
2e500 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
2e510 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e520 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2e530 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
2e540 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
2e550 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
2e560 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e570 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
2e580 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
2e590 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
2e5a0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2e5b0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
2e5c0 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63  .** {F16621} A c
2e5d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e5e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e5f0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
2e600 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
2e610 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
2e620 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
2e630 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e640 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
2e650 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2e660 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
2e670 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
2e680 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ctor..**.** {F16
2e690 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
2e6a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e6b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e6c0 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
2e6d0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
2e6e0 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
2e6f0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
2e700 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
2e710 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
2e720 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
2e730 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e740 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74  ction] B on text
2e750 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20   values that.** 
2e760 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65           use the
2e770 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
2e780 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a  nce name X..**.*
2e790 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b  * {F16627} The [
2e7a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e7b0 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45  ollation16(B,X,E
2e7c0 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65  ,P,F)] works the
2e7d0 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
2e7e0 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72    as [sqlite3_cr
2e7f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
2e800 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70  ,X,E,P,F)] excep
2e810 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  t that the.**   
2e820 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e         collation
2e830 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72   name X is under
2e840 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20  stood as UTF-16 
2e850 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
2e860 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
2e870 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
2e880 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30  8..**.** {F16630
2e890 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  } When multiple 
2e8a0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e8b0 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
2e8c0 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a  le for the same.
2e8d0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
2e8e0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
2e8f0 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74  SQLite chooses t
2e900 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78  he one whose tex
2e910 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20  t encoding.**   
2e920 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20         requires 
2e930 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2e940 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66   of conversion f
2e950 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a  rom the default.
2e960 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
2e970 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2e980 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e   database..*/.in
2e990 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e9a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
2e9b0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2e9c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2e9d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2e9e0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2e9f0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2ea00 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2ea10 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2ea20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2ea30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ea40 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
2ea50 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2ea60 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2ea70 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2ea80 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2ea90 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2eaa0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2eab0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
2eac0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2ead0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2eae0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2eaf0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
2eb00 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2eb10 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2eb20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2eb30 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2eb40 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2eb50 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2eb60 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2eb70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb80 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2eb90 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37   Callbacks {F167
2eba0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00}.**.** To avo
2ebb0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
2ebc0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
2ebd0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
2ebe0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
2ebf0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
2ec00 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
2ec10 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2ec20 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
2ec30 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  h the.** databas
2ec40 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63  e handle to be c
2ec50 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
2ec60 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
2ec70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2ec80 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a  s.** required..*
2ec90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
2eca0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2ecb0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2ecc0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2ecd0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2ece0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2ecf0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2ed00 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2ed10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2ed20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2ed30 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31  ed in UTF-8. {F1
2ed40 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
2ed50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2ed60 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74  d16() is used, t
2ed70 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20  he names.** are 
2ed80 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
2ed90 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
2eda0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41  ve byte order. A
2edb0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a   call to either.
2edc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  ** function repl
2edd0 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
2ede0 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
2edf0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
2ee00 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
2ee10 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ee20 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
2ee30 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
2ee40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
2ee50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ee60 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
2ee70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
2ee80 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
2ee90 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2eea0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
2eeb0 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20  base.** handle. 
2eec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2eed0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2eee0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2eef0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2ef00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2ef10 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2ef20 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65  g the most.** de
2ef30 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2ef40 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
2ef50 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2ef60 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65  required..** The
2ef70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ef80 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2ef90 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
2efa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2efb0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
2efc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2efd0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2efe0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2eff0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2f000 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f010 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2f020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2f030 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2f040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2f050 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2f060 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
2f070 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2f080 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66  6702} A successf
2f090 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2f0a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f0b0 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20  eded(D,P,F)].** 
2f0c0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2f0d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f0e0 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20  eeded16(D,P,F)] 
2f0f0 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20  causes.**       
2f100 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
2f110 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
2f120 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63  o invoke callbac
2f130 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a  k F with first.*
2f140 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
2f150 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20  eter P whenever 
2f160 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61  it needs a compa
2f170 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66  rison function f
2f180 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  or a.**         
2f190 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
2f1a0 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  nce that it does
2f1b0 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e   not know about.
2f1c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20  .**.** {F16704} 
2f1d0 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20  Each successful 
2f1e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f1f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f200 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  d()] or.**      
2f210 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
2f220 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2f230 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
2f240 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74   callback regist
2f250 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
2f260 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2f270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f280 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  n] by prior call
2f290 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20  s to either.**  
2f2a0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f2b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36  e..**.** {F16706
2f2c0 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  } The name of th
2f2d0 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c  e requested coll
2f2e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  ating function p
2f2f0 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  assed in the.** 
2f300 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72           4th par
2f310 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
2f320 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46  llback is in UTF
2f330 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  -8 if the callba
2f340 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ck.**          w
2f350 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  as registered us
2f360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
2f370 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2f380 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2f390 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61   is in UTF-16 na
2f3a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2f3b0 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
2f3c0 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
2f3d0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2f3e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2f3f0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
2f400 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73  .**.** .*/.int s
2f410 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f420 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2f430 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2f440 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2f450 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2f460 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2f470 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2f480 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f490 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2f4a0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2f4b0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2f4c0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2f4d0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2f4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2f4f0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
2f500 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
2f510 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
2f520 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
2f530 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
2f540 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
2f550 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2f560 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2f570 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2f580 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2f590 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2f5a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2f5b0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
2f5c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2f5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f5e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2f5f0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2f600 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2f610 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2f620 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
2f630 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
2f640 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
2f650 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
2f660 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
2f670 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
2f680 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
2f690 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
2f6a0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
2f6b0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
2f6c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
2f6d0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
2f6e0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2f6f0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2f700 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2f710 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2f720 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2f730 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2f740 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
2f750 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2f760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f770 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2f780 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2f790 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2f7a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2f7b0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
2f7c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f7d0 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  :  Suspend Execu
2f7e0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2f7f0 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a   Time {F10530}.*
2f800 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f810 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2f820 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20  n.** causes the 
2f830 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2f840 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2f850 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2f860 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2f870 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2f880 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2f890 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2f8a0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2f8b0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2f8c0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2f8d0 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20  quests with .** 
2f8e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
2f8f0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
2f900 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
2f910 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
2f920 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74   .** the nearest
2f930 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
2f940 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2f950 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2f960 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73  ually .** reques
2f970 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2f980 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2f990 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f9a0 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
2f9b0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
2f9c0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
2f9d0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
2f9e0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
2f9f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
2fa00 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
2fa10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2fa20 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {F10533} The [s
2fa30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
2fa40 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
2fa50 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
2fa60 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
2fa70 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2fa80 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
2fa90 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
2faa0 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
2fab0 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
2fac0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
2fad0 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
2fae0 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
2faf0 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
2fb00 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {F10536} The [s
2fb10 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
2fb20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fb30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fb40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
2fb50 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2fb60 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
2fb70 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
2fb80 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
2fb90 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
2fba0 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
2fbb0 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
2fbc0 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
2fbd0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
2fbe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fbf0 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  F:  Name Of The 
2fc00 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2fc10 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
2fc20 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66  F10310}.**.** If
2fc30 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2fc40 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2fc50 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2fc60 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2fc70 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2fc80 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63  der (a.ka. direc
2fc90 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2fca0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2fcb0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2fcc0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
2fcd0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2fce0 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
2fcf0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e  variable.** is N
2fd00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2fd10 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20  n SQLite does a 
2fd20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
2fd30 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72  propriate tempor
2fd40 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65  ary.** file dire
2fd50 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
2fd60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
2fd70 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2fd80 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62  ble once a datab
2fd90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
2fda0 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
2fdb0 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
2fdc0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2fdd0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2fde0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2fdf0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2fe00 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2fe10 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2fe20 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2fe30 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2fe40 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
2fe50 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
2fe60 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
2fe70 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
2fe80 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
2fe90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fea0 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20  F:  Test To See 
2feb0 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20  If The Database 
2fec0 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
2fed0 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a  t Mode {F12930}.
2fee0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2fef0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2ff00 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  () interfaces re
2ff10 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2ff20 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2ff30 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2ff40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2ff50 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2ff60 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2ff70 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41  espectively.   A
2ff80 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2ff90 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75  s on.** by defau
2ffa0 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  lt.  Autocommit 
2ffb0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2ffc0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2ffd0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
2ffe0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
2fff0 65 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  eenabled by a [C
30000 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
30010 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
30020 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
30030 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
30040 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
30050 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
30060 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
30070 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63  ions (errors inc
30080 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
30090 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
300a0 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  ERR], .** [SQLIT
300b0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
300c0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
300d0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
300e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
300f0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
30100 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
30110 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
30120 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
30130 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c   find out if SQL
30140 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
30150 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
30160 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
30170 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
30180 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
30190 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
301a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
301b0 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73   {F12931} The [s
301c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
301d0 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66  ommit(D)] interf
301e0 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
301f0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20  zero or.**      
30200 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20      zero if the 
30210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30220 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73  tion] D is or is
30230 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
30240 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
30250 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
30260 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32  y..**.** {F12932
30270 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
30280 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
30290 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  lt..**.** {F1293
302a0 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
302b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
302c0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
302d0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
302e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d  ..**.** {F12934}
302f0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
30300 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
30310 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
30320 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
30330 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
30340 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a  tatement..** .**
30350 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
30360 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d  .***.** {U12936}
30370 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
30380 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
30390 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
303a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
303b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
303c0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
303d0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
303e0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
303f0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
30400 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
30410 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
30420 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
30430 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
30440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30450 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
30460 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
30470 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30480 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a  nt {F13120}.**.*
30490 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
304a0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
304b0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
304c0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
304d0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77  base handle to w
304e0 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61  hich a.** [prepa
304f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
30500 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64  elongs..** The d
30510 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
30520 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30530 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20  e3_db_handle.** 
30540 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
30550 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
30560 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73   was.** the firs
30570 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30580 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30590 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
305a0 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74  variants.** that
305b0 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65   was used to cre
305c0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
305d0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
305e0 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lace..**.** INVA
305f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30600 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  13123} The [sqli
30610 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29  te3_db_handle(S)
30620 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
30630 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
30640 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
30650 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30660 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
30670 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
30680 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
30690 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
306a0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
306b0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
306c0 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
306d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
306e0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
306f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
30700 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a  backs {F12950}.*
30710 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30720 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
30730 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30740 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30750 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30760 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30770 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30780 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30790 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
307a0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
307b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
307c0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
307d0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
307e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
307f0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
30800 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30810 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
30820 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
30830 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
30840 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30850 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30860 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30870 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
30880 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
30890 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
308a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
308b0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
308c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
308d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
308e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
308f0 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
30900 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
30910 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
30920 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
30930 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
30940 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
30950 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
30960 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
30970 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
30980 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
30990 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
309a0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
309b0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
309c0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
309d0 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
309e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
309f0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
30a00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30a10 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
30a20 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
30a30 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
30a40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
30a50 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
30a60 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
30a70 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
30a80 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72   have been .** r
30a90 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
30aa0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
30ab0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
30ac0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
30ad0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
30ae0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
30af0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
30b00 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
30b10 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
30b20 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
30b30 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
30b40 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
30b50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
30b60 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
30b70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30b80 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
30b90 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
30ba0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
30bb0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
30bc0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
30bd0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
30be0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
30bf0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
30c00 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
30c10 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
30c20 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
30c30 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72   These are exper
30c40 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
30c50 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65  es and are subje
30c60 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a  ct to change..**
30c70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
30c80 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54  **.** {F12951} T
30c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
30ca0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
30cb0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
30cc0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
30cd0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
30ce0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
30cf0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
30d00 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
30d10 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
30d20 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
30d30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
30d40 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
30d50 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20  ** {F12952} The 
30d60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
30d70 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
30d80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30d90 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
30da0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
30db0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
30dc0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
30dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
30de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30df0 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
30e00 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
30e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
30e20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
30e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30e40 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
30e50 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
30e60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
30e70 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
30e80 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
30e90 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
30ea0 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
30eb0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
30ec0 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {F12954} If the 
30ed0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
30ee0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30ef0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
30f00 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
30f10 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
30f20 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
30f30 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f  cancelled and no
30f40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
30f50 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
30f60 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
30f70 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a  ion commits..**.
30f80 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74  ** {F12955} If t
30f90 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61  he commit callba
30fa0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
30fb0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ero then the com
30fc0 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  mit is.**       
30fd0 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74     converted int
30fe0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
30ff0 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65  .** {F12961} The
31000 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
31010 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
31020 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
31030 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
31040 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
31050 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
31060 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
31070 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
31080 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
31090 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
310a0 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ack on [database
310b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
310c0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54  **.** {F12962} T
310d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
310e0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
310f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
31100 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
31110 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
31120 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
31130 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
31140 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame .**         
31150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31160 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e  ction ] D , or N
31170 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
31180 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
31190 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
311a0 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ar [database con
311b0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
311c0 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20  * {F12963} Each 
311d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
311e0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
311f0 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
31200 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
31210 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
31220 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
31230 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20  .**.** {F12964} 
31240 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
31250 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
31260 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
31270 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
31280 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
31290 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
312a0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
312b0 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c  lled and no call
312c0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
312d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
312e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72   a transaction r
312f0 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f  olls back..*/.vo
31300 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
31310 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
31320 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
31330 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
31340 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
31350 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
31360 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
31370 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
31380 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
31390 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
313a0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
313b0 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  970}.**.** The s
313c0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
313d0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ok() interface.*
313e0 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  * registers a ca
313f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
31400 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
31410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
31420 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
31430 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
31440 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
31450 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
31460 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
31470 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
31480 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
31490 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
314a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
314b0 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  unction for the 
314c0 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  same .** databas
314d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
314e0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
314f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
31500 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
31510 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
31520 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
31530 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75  n a .** row is u
31540 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
31550 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a   or deleted. .**
31560 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
31570 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
31580 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79  ack is.** a copy
31590 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
315a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
315b0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
315c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
315d0 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75  allback .** argu
315e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
315f0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
31600 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
31610 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
31620 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  E],.** depending
31630 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
31640 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
31650 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65  e callback to be
31660 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65   invoked..** The
31670 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66   third and .** f
31680 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
31690 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
316a0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
316b0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
316c0 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e   and .** table n
316d0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
316e0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
316f0 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61  .** The final ca
31700 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
31710 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69   is .** the rowi
31720 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  d of the row..**
31730 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
31740 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
31750 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
31760 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74  er .** the updat
31770 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
31780 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
31790 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
317a0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
317b0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
317c0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
317d0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
317e0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
317f0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
31800 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
31810 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
31820 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
31830 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
31840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
31850 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
31860 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31870 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31880 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20  ** {F12971} The 
31890 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
318a0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
318b0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
318c0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
318d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f     function F to
318e0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
318f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
31900 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
31910 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20          a table 
31920 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c  row is modified,
31930 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65   inserted, or de
31940 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  leted on.**     
31950 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
31960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
31970 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65  .** {F12973} The
31980 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
31990 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
319a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
319b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
319c0 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74        of P for t
319d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
319e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
319f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31a00 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20  n] D,.**        
31a10 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68    or NULL for th
31a20 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a  e first call..**
31a30 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20  .** {F12975} If 
31a40 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  the update hook 
31a50 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73  callback F in [s
31a60 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31a70 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20  ok(D,F,P)].**   
31a80 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74         is NULL t
31a90 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74  hen the no updat
31aa0 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  e callbacks are 
31ab0 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  made..**.** {F12
31ac0 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  977} Each call t
31ad0 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  o [sqlite3_updat
31ae0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f  e_hook(D,F,P)] o
31af0 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63  verrides prior c
31b00 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
31b10 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74   to the same int
31b20 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61  erface on the sa
31b30 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
31b40 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
31b50 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75  * {F12979} The u
31b60 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
31b70 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
31b80 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
31b90 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20   system.**      
31ba0 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20      tables such 
31bb0 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  as sqlite_master
31bc0 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
31bd0 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65  ence are modifie
31be0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31  d..**.** {F12981
31bf0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
31c00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70  ameter to the up
31c10 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  date callback .*
31c20 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
31c30 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
31c40 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
31c50 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
31c60 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
31c70 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
31c80 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
31c90 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
31ca0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
31cb0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
31cc0 46 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  F12983} The thir
31cd0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
31ce0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
31cf0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
31d00 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
31d10 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
31d20 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
31d30 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
31d40 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
31d50 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
31d60 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
31d70 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
31d80 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38  ated...** {F1298
31d90 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
31da0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
31db0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
31dc0 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
31dd0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
31de0 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
31df0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
31e00 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
31e10 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
31e20 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
31e30 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
31e40 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
31e50 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
31e60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31e70 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44  EF:  Enable Or D
31e80 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
31e90 67 65 72 20 43 61 63 68 65 20 7b 46 31 30 33 33  ger Cache {F1033
31ea0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
31eb0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
31ec0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
31ed0 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
31ee0 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
31ef0 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
31f00 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
31f10 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f  n connections to
31f20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
31f30 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69  se..** Sharing i
31f40 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
31f50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
31f60 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  e and disabled i
31f70 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  f the argument.*
31f80 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  * is false..**.*
31f90 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
31fa0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
31fb0 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61  isabled.** for a
31fc0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
31fd0 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20  . {END} This is 
31fe0 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
31ff0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
32000 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72  5.0..** In prior
32010 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
32020 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73  ite, sharing was
32030 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  .** enabled or d
32040 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
32050 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
32060 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ly..**.** The ca
32070 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  che sharing mode
32080 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74   set by this int
32090 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61  erface effects a
320a0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  ll subsequent.**
320b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
320c0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
320d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
320e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
320f0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73  en16()]..** Exis
32100 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f  ting database co
32110 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  nnections contin
32120 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69  ue use the shari
32130 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20  ng mode.** that 
32140 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74  was in effect at
32150 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77   the time they w
32160 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  ere opened..**.*
32170 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
32180 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20   cannot be used 
32190 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61  with a shared ca
321a0 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72  che.   When shar
321b0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
321c0 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
321d0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
321e0 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
321f0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
32200 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
32210 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
32220 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
32230 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
32240 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
32250 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
32260 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
32270 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
32280 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
32290 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
322a0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
322b0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
322c0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
322d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
322e0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
322f0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
32300 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
32310 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
32320 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
32330 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
32340 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
32350 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
32360 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  citly..**.** INV
32370 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20  ARIANTS:.** .** 
32380 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63 63 65  {F10331} A succe
32390 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
323a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   of [sqlite3_ena
323b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
323c0 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (B)].**         
323d0 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20   will enable or 
323e0 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63  disable shared c
323f0 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e  ache mode for an
32400 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a  y subsequently.*
32410 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74  *          creat
32420 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
32430 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20  nection] in the 
32440 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  same process..**
32450 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65  .** {F10336} Whe
32460 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69  n shared cache i
32470 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
32480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
32490 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  odule()].**     
324a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77       interface w
324b0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
324c0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
324d0 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b  * {F10337} The [
324e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
324f0 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20  hared_cache(B)] 
32500 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32510 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
32520 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
32530 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
32540 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
32550 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a  d successfully..
32560 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53  **.** {F10339} S
32570 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
32580 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
32590 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  lt..*/.int sqlit
325a0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
325b0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
325c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41  .** CAPI3REF:  A
325d0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
325e0 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33  eap Memory {F173
325f0 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
32600 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32610 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
32620 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20   attempts to.** 
32630 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
32640 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
32650 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
32660 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
32670 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  .** allocations 
32680 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
32690 62 61 73 65 20 6c 61 62 72 61 72 79 2e 20 7b 45  base labrary. {E
326a0 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  ND}  Memory used
326b0 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74  .** to cache dat
326c0 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69  abase pages to i
326d0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
326e0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
326f0 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e   of.** non-essen
32700 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71  tial memory.  Sq
32710 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32720 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a  mory() returns.*
32730 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32740 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
32750 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68  reed, which migh
32760 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
32770 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d  s.** than the am
32780 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
32790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
327a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d  :.**.** {F17341}
327b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
327c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d  lease_memory(N)]
327d0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
327e0 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  pts to.**       
327f0 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 73 20     free N bytes 
32800 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
32810 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
32820 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20  on-essential.** 
32830 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
32840 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64  allocations held
32850 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
32860 20 6c 61 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   labrary..**.** 
32870 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71  {F16342} The [sq
32880 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32890 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73  mory(N)] returns
328a0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
328b0 20 20 20 20 20 20 20 20 6f 66 20 62 79 74 65 73          of bytes
328c0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
328d0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
328e0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20  more or less.** 
328f0 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 74 68           than th
32900 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
32910 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
32920 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32930 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
32940 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65  API3REF:  Impose
32950 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
32960 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a   Size {F17350}.*
32970 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32980 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
32990 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
329a0 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
329b0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
329c0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
329d0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
329e0 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53  llocated.** by S
329f0 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74  QLite. If an int
32a00 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e  ernal allocation
32a10 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a   is requested .*
32a20 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  * that would exc
32a30 65 65 64 20 74 68 65 20 73 6f 66 74 20 68 65 61  eed the soft hea
32a40 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65  p limit, [sqlite
32a50 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32a60 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65  ()] is.** invoke
32a70 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
32a80 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73  mes to free up s
32a90 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65  ome space before
32aa0 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a   the allocation.
32ab0 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  ** is made..**.*
32ac0 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63  * The limit is c
32ad0 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
32ae0 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c  cause if.** [sql
32af0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
32b00 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a  ory()] cannot.**
32b10 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
32b20 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
32b30 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
32b40 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
32b50 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
32b60 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
32b70 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
32b80 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
32b90 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  oceeds..**.** A 
32ba0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
32bb0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
32bc0 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
32bd0 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
32be0 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
32bf0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
32c00 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
32c10 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
32c20 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
32c30 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ed..** The defau
32c40 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
32c50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32c60 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
32c70 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
32c80 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
32c90 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
32ca0 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75  p limit.  .** Bu
32cb0 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65  t if the soft he
32cc0 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20  ap limit cannot 
32cd0 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69  honored, executi
32ce0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69  on will.** conti
32cf0 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f  nue without erro
32d00 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f  r or notificatio
32d10 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20  n.  This is why 
32d20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a  the limit is .**
32d30 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
32d40 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
32d50 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
32d60 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
32d70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
32d80 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
32d90 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
32da0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
32db0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
32dc0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
32dd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32de0 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
32df0 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
32e00 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
32e10 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
32e20 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
32e30 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
32e40 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
32e50 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
32e60 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
32e70 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32e80 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
32e90 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
32ea0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
32eb0 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
32ec0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
32ed0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
32ee0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
32ef0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
32f00 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
32f10 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
32f20 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  reads..**.** INV
32f30 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
32f40 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16351} The [sql
32f50 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32f60 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61  imit(N)] interfa
32f70 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74  ce places a soft
32f80 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
32f90 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e     of N bytes on
32fa0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
32fb0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
32fc0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
32fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69  .**          usi
32fe0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
32ff0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
33000 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20  3_realloc()] at 
33010 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20  any point.**    
33020 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a        in time..*
33030 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66  *.** {F16352} If
33040 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
33050 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
33060 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
33070 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20  c()] would.**   
33080 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65         cause the
33090 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66   total amount of
330a0 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
330b0 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  y to exceed the.
330c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74  **          soft
330d0 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65   heap limit, the
330e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  n [sqlite3_relea
330f0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
33100 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20  invoked.**      
33110 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70      in an attemp
33120 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20  t to reduce the 
33130 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69  memory usage pri
33140 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67  or to proceeding
33150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
33160 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  h the memory all
33170 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e  ocation attempt.
33180 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20  .**.** {F16353} 
33190 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
331a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
331b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
331c0 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a  )] that trigger.
331d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65  **          atte
331e0 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d  mpts to reduce m
331f0 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f  emory usage thro
33200 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61  ugh the soft hea
33210 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  p limit.**      
33220 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f      mechanism co
33230 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74  ntinue even if t
33240 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  he attempt to re
33250 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  duce memory.**  
33260 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73          usage is
33270 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a   unsuccessful..*
33280 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20  *.** {F16354} A 
33290 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
332a0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20   value for N in 
332b0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
332c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
332d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
332e0 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  )] means that th
332f0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a  ere is no soft.*
33300 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20  *          heap 
33310 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74  limit and [sqlit
33320 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
33330 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
33340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
33350 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
33360 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65   is completely e
33370 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  xhausted..**.** 
33380 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66  {F16355} The def
33390 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
333a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
333b0 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
333c0 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20  * {F16358} Each 
333d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
333e0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
333f0 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  (N)] overrides t
33400 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
33410 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c  alues set by all
33420 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f   prior calls..*/
33430 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
33440 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
33450 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33460 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65  REF:  Extract Me
33470 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
33480 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
33490 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12850}.**.** 
334a0 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
334b0 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
334c0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
334d0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
334e0 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
334f0 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
33500 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
33510 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
33520 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
33530 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
33540 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
33550 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
33560 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
33570 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
33580 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
33590 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
335a0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
335b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
335c0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
335d0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
335e0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
335f0 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
33600 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
33610 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
33620 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
33630 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
33640 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
33650 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
33660 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
33670 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
33680 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
33690 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
336a0 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
336b0 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
336c0 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
336d0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
336e0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
336f0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
33700 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
33710 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
33720 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
33730 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
33740 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
33750 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
33760 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
33770 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
33780 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
33790 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
337a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
337b0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
337c0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
337d0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
337e0 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
337f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33800 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
33810 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
33820 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
33830 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
33840 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
33850 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
33860 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
33870 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
33880 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64  tion is ommitted
33890 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
338a0 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
338b0 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
338c0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
338d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
338e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
338f0 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
33900 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
33910 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
33920 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
33930 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
33940 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
33950 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
33960 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
33970 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
33980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
33990 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
339a0 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
339b0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
339c0 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
339d0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
339e0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
339f0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
33a00 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
33a10 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
33a20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
33a30 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
33a40 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
33a50 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
33a60 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
33a70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
33a80 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
33a90 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
33aa0 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
33ab0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
33ac0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33ad0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
33ae0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
33af0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
33b00 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
33b10 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
33b20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
33b30 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
33b40 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
33b50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
33b60 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
33b70 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
33b80 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
33b90 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
33ba0 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
33bb0 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
33bc0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
33bd0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
33be0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
33bf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
33c00 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
33c10 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
33c20 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
33c30 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
33c40 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
33c50 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
33c60 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
33c70 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
33c80 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
33c90 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
33ca0 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
33cb0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
33cc0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33cd0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
33ce0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
33cf0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
33d00 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
33d10 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
33d20 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
33d30 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
33d40 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
33d50 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
33d60 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
33d70 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
33d80 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
33d90 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
33da0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
33db0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
33dc0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
33dd0 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
33de0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
33df0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
33e00 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
33e10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
33e20 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
33e30 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
33e40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
33e50 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
33e60 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
33e70 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
33e80 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
33e90 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
33ea0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
33eb0 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
33ec0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
33ed0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
33ee0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
33ef0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
33f00 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33f10 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
33f20 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
33f30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
33f40 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
33f50 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
33f60 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
33f70 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
33f80 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
33f90 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
33fa0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
33fb0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
33fc0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
33fd0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
33fe0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
33ff0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
34000 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
34010 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
34020 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
34030 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
34040 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
34050 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
34060 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
34070 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
34080 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
34090 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
340a0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
340b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
340c0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
340d0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
340e0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
340f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34100 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
34110 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
34120 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
34130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34140 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
34150 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a  ion {F12600}.**.
34160 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20  ** {F12601} The 
34170 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
34180 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
34190 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74  ce.** attempts t
341a0 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
341b0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
341c0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
341d0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
341e0 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20  e. {F12602} The 
341f0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
34200 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a  Proc. {F12603} z
34210 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a  Proc may be 0.**
34220 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
34230 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
34240 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
34250 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74  lts.** to "sqlit
34260 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
34270 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  t"..**.** {F1260
34280 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
34290 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
342a0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a  interface shall.
342b0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
342c0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
342d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
342e0 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
342f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
34300 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49  ** {F12605}.** I
34310 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
34320 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
34330 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
34340 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61  e.** sqlite3_loa
34350 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
34360 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
34370 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70  tempt to fill *p
34380 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
34390 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
343a0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
343b0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
343c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
343d0 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20  oc()]..** {END} 
343e0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
343f0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65  ction should fre
34400 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a  e this memory.**
34410 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
34420 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
34430 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20  .** {F12606}.** 
34440 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
34450 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
34460 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34470 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34480 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69  ension()].** pri
34490 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
344a0 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72  is API or an err
344b0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
344c0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
344d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
344e0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
344f0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
34500 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
34510 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
34520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34530 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
34540 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
34550 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
34560 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
34570 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
34580 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34590 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
345a0 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
345b0 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
345c0 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
345d0 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
345e0 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
345f0 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
34600 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
34610 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
34620 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
34630 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
34640 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  620}.**.** So as
34650 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
34660 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
34670 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
34680 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
34690 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
346a0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
346b0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
346c0 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
346d0 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
346e0 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
346f0 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
34700 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
34710 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
34720 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
34730 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
34740 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
34750 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
34760 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b  n and.** off.  {
34770 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66  F12622} It is of
34780 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45  f by default. {E
34790 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23  ND} See ticket #
347a0 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  1863..**.** {F12
347b0 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71  621} Call the sq
347c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
347d0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
347e0 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e  utine.** with on
347f0 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65  off==1 to turn e
34800 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
34810 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20   on.** and call 
34820 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
34830 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b   to turn it back
34840 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44   off again. {END
34850 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
34860 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34870 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
34880 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
34890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
348a0 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e   Make Arrangemen
348b0 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61  ts To Automatica
348c0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
348d0 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a  nsion {F12640}.*
348e0 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68  *.** {F12641} Th
348f0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  is function.** r
34900 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
34910 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
34920 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
34930 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
34940 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
34950 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
34960 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
34970 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
34980 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
34990 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
349a0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
349b0 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  v2()]. {END}.**.
349c0 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
349d0 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
349e0 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
349f0 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
34a00 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
34a10 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
34a20 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
34a30 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
34a40 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
34a50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
34a60 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
34a70 7b 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61  {F12642} Duplica
34a80 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
34a90 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
34aa0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
34ab0 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  ne multiple.** t
34ac0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
34ad0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
34ae0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
34af0 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f  {F12643} This ro
34b00 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
34b10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
34b20 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
34b30 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f  ray.** that is o
34b40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
34b50 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45  ite_malloc(). {E
34b60 4e 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61  ND} If you run a
34b70 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20   memory leak.** 
34b80 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20  checker on your 
34b90 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72  program and it r
34ba0 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65  eports a leak be
34bb0 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
34bc0 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76   array, then inv
34bd0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  oke [sqlite3_res
34be0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
34bf0 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  n()] prior.** to
34c00 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65   shutdown to fre
34c10 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  e the memory..**
34c20 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74  .** {F12644} Aut
34c30 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
34c40 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
34c50 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44  ll threads. {END
34c60 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
34c70 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
34c80 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
34c90 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
34ca0 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
34cb0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
34cc0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
34cd0 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
34ce0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a  extension(void *
34cf0 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a  xEntryPoint);...
34d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34d10 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
34d20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
34d30 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a  g {F12660}.**.**
34d40 20 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66   {F12661} This f
34d50 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
34d60 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
34d70 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75  registered.** au
34d80 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
34d90 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a  ns. {END}  This.
34da0 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
34db0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
34dc0 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74  all prior [sqlit
34dd0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34de0 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a  n()].** calls..*
34df0 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68  *.** {F12662} Th
34e00 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64  is call disabled
34e10 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
34e20 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  sions in all thr
34e30 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  eads. {END}.**.*
34e40 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
34e50 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
34e60 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
34e70 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
34e80 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
34e90 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
34ea0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
34eb0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
34ec0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
34ed0 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  ;.../*.****** EX
34ee0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
34ef0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
34f00 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
34f10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
34f20 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
34f30 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
34f40 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
34f50 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
34f60 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
34f70 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
34f80 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
34f90 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
34fa0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
34fb0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
34fc0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
34fd0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
34fe0 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
34ff0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
35000 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
35010 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
35020 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69  stablizes, we wi
35030 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
35040 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
35050 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
35060 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
35070 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
35080 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
35090 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
350a0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
350b0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
350c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
350d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
350e0 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
350f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
35100 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
35110 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
35120 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35130 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35140 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
35150 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
35160 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35170 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
35180 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
35190 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
351a0 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31  Table Object {F1
351b0 38 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  8000}.** KEYWORD
351c0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
351d0 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65  e.**.** A module
351e0 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76   is a class of v
351f0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20  irtual tables.  
35200 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64  Each module is d
35210 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20  efined.** by an 
35220 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
35230 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
35240 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63  ure.  This struc
35250 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a  ture consists.**
35260 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
35270 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
35280 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  e..*/.struct sql
35290 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
352a0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
352b0 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
352c0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
352d0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
352e0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
352f0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
35300 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
35310 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
35320 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
35330 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
35340 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
35350 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
35360 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
35370 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
35380 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
35390 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
353a0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
353b0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
353c0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
353d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
353e0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
353f0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
35400 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
35410 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35420 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35430 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
35440 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35450 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
35460 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35470 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
35480 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
35490 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
354a0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
354b0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
354c0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
354d0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
354e0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
354f0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
35500 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35510 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
35520 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
35530 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
35540 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
35550 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
35560 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
35570 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
35580 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
35590 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
355a0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
355b0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
355c0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
355d0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
355e0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
355f0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
35600 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
35610 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
35620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
35630 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
35640 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
35650 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
35660 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
35670 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
35680 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35690 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
356a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
356b0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
356c0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
356d0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
356e0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
356f0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
35700 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
35710 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
35720 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
35730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35740 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
35750 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35760 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35770 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
35780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
35790 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20  id **ppArg);..  
357a0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
357b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
357c0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
357d0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
357e0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
357f0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
35800 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46  g Information {F
35810 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18100}.** KEYWOR
35820 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
35830 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
35840 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35850 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
35860 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
35870 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
35880 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
35890 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
358a0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
358b0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
358c0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
358d0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
358e0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
358f0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
35900 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
35910 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
35920 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
35930 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
35940 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
35950 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
35960 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
35970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
35980 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
35990 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
359a0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
359b0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
359c0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
359d0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
359e0 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
359f0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
35a00 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
35a10 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
35a20 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
35a30 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
35a40 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
35a50 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
35a60 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
35a70 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
35a80 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
35a90 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
35aa0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
35ab0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
35ac0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
35ad0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
35ae0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
35af0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
35b00 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
35b10 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
35b20 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
35b30 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
35b40 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
35b50 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
35b60 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
35b70 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
35b80 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
35b90 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
35ba0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
35bb0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
35bc0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
35bd0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
35be0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
35bf0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
35c00 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
35c10 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
35c20 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
35c30 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
35c40 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
35c50 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
35c60 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
35c70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
35c80 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
35c90 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
35ca0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
35cb0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
35cc0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
35cd0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
35ce0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
35cf0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
35d00 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
35d10 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
35d20 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
35d30 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
35d40 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
35d50 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
35d60 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
35d70 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
35d80 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
35d90 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
35da0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
35db0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
35dc0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
35dd0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
35de0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
35df0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
35e00 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
35e10 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
35e20 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
35e30 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
35e40 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
35e50 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
35e60 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
35e70 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
35e80 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
35e90 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
35ea0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
35eb0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
35ec0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
35ed0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
35ee0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
35ef0 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
35f00 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
35f10 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
35f20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
35f30 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
35f40 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
35f50 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
35f60 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
35f70 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
35f80 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
35f90 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
35fa0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
35fb0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
35fc0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
35fd0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
35fe0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
35ff0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
36000 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
36010 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
36020 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
36030 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
36040 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
36050 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
36060 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
36070 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
36080 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
36090 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
360a0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
360b0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
360c0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
360d0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
360e0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
360f0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
36100 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
36110 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
36120 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
36130 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
36140 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
36150 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
36160 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
36170 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
36180 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
36190 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
361a0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
361b0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
361c0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
361d0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
361e0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
361f0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
36200 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
36210 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
36220 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
36230 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
36240 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
36250 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
36260 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
36270 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
36280 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
36290 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
362a0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
362b0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
362c0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
362d0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
362e0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
362f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
36300 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
36310 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
36320 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36330 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
36340 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
36350 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
36360 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
36370 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
36380 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
36390 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
363a0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
363b0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
363c0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
363d0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
363e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
363f0 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
36400 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36410 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
36420 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
36430 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
36440 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
36450 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
36460 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
36470 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
36480 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
36490 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
364a0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
364b0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
364c0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
364d0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
364e0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
364f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
36500 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
36510 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
36520 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
36530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36540 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
36550 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36560 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
36570 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
36580 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
36590 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
365a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
365b0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
365c0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
365d0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
365e0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
365f0 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
36600 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
36610 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
36620 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
36630 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
36640 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
36650 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36660 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
36670 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
36680 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36690 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
366a0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
366b0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
366c0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
366d0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
366e0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
366f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36700 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
36710 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
36720 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
36730 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
36740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36750 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
36760 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
36770 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d  ntation {F18200}
36780 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
36790 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
367a0 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f  egister a new mo
367b0 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61  dule name with a
367c0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e  n SQLite.** conn
367d0 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20  ection.  Module 
367e0 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65  names must be re
367f0 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20  gistered before 
36800 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20  creating new.** 
36810 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f  virtual tables o
36820 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72  n the module, or
36830 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72   before using pr
36840 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61  eexisting virtua
36850 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74  l.** tables of t
36860 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e  he module..*/.in
36870 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36880 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
36890 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
368a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
368b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
368c0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
368d0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
368e0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
368f0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36900 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
36910 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
36920 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68  le *,    /* Meth
36930 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
36940 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20  le */.  void *  
36950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36960 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
36970 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
36980 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
36990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
369a0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
369b0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
369c0 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a  ation {F18210}.*
369d0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
369e0 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  e is identical t
369f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
36a00 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65  eate_module() me
36a10 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65  thod above,.** e
36a20 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
36a30 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f  lows a destructo
36a40 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  r function to be
36a50 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69   specified. It i
36a60 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65  s.** even more e
36a70 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e  xperimental than
36a80 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65   the rest of the
36a90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
36aa0 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  API..*/.int sqli
36ab0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36ac0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
36ad0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36ae0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
36af0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
36b00 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
36b10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36b20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
36b30 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
36b40 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
36b50 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36b60 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
36b70 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
36b80 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
36b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ba0 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
36bb0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
36bc0 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
36bd0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
36be0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
36bf0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
36c00 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
36c10 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36c20 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
36c30 4f 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d 0a  Object {F18010}.
36c40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
36c50 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
36c60 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
36c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
36c80 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
36c90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
36ca0 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
36cb0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
36cc0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
36cd0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
36ce0 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
36cf0 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
36d00 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
36d10 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
36d20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36d30 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
36d40 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
36d50 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
36d60 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
36d70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
36d80 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
36d90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
36da0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
36db0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
36dc0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
36dd0 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
36de0 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
36df0 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
36e00 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
36e10 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
36e20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
36e30 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
36e40 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
36e50 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
36e60 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
36e70 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
36e80 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
36e90 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
36ea0 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
36eb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
36ec0 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
36ed0 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
36ee0 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
36ef0 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
36f00 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
36f10 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
36f20 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
36f30 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
36f40 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
36f50 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
36f60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36f70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
36f80 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
36f90 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
36fa0 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
36fb0 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
36fc0 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
36fd0 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
36fe0 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
36ff0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
37000 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
37010 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
37020 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
37030 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37040 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
37050 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
37060 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
37070 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
37080 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
37090 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
370a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
370b0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
370c0 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
370d0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
370e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
370f0 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
37100 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37110 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
37120 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37130 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37140 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37150 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37160 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37170 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
37180 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20  e Cursor Object 
37190 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59   {F18020}.** KEY
371a0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
371b0 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a  tab_cursor.**.**
371c0 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
371d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
371e0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
371f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
37200 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
37210 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37220 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37230 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
37240 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
37250 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
37260 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
37270 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
37280 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
37290 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68  he.** xOpen meth
372a0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
372b0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
372c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
372d0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
372e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
372f0 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
37300 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
37310 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
37320 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
37330 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
37340 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
37350 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
37360 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
37370 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
37380 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
37390 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
373a0 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
373b0 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
373c0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
373d0 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
373e0 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
373f0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37400 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37410 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37420 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37430 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37440 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
37450 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
37460 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32 38  ual Table {F1828
37470 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  0}.**.** The xCr
37480 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
37490 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d  t methods of a m
374a0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f  odule use the fo
374b0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74  llowing API.** t
374c0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
374d0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
374e0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
374f0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
37500 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
37510 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
37520 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
37530 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
37540 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
37550 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
37560 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Table);../*.** C
37570 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
37580 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
37590 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
375a0 20 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F18300}.**.** 
375b0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
375c0 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72  an provide alter
375d0 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
375e0 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69  ations of functi
375f0 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ons.** using the
37600 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d   xFindFunction m
37610 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62  ethod.  But glob
37620 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
37630 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
37640 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
37650 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
37660 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  loaded..**.** Th
37670 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
37680 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
37690 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
376a0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
376b0 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
376c0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
376d0 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
376e0 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
376f0 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
37700 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
37710 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
37720 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
37730 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
37740 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37750 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
37760 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
37770 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
37780 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
37790 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
377a0 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
377b0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
377c0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
377d0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
377e0 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75   place-holder fu
377f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
37800 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
37810 20 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c   by virtual tabl
37820 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  es..**.** This A
37830 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e  PI should be con
37840 73 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20  sidered part of 
37850 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
37860 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  e interface,.** 
37870 77 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d  which is experim
37880 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63  ental and subjec
37890 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
378a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
378b0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
378c0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
378d0 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
378e0 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
378f0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
37900 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
37910 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
37920 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
37930 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
37940 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
37950 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
37960 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
37970 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
37980 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
37990 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
379a0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
379b0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
379c0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
379d0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
379e0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
379f0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
37a00 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
37a10 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
37a20 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
37a30 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
37a40 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
37a50 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
37a60 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
37a70 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
37a80 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
37a90 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  s comment..**.**
37aa0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
37ab0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
37ac0 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
37ad0 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
37ae0 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ***.*/../*.** CA
37af0 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
37b00 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
37b10 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17800}.**.** 
37b20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
37b30 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
37b40 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
37b50 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69  OB on which.** i
37b60 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63  ncremental I/O c
37b70 61 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e  an be preformed.
37b80 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
37b90 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
37ba0 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
37bb0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
37bc0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
37bd0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
37be0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
37bf0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
37c00 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
37c10 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
37c20 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
37c30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
37c40 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
37c50 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
37c60 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
37c70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37c80 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
37c90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
37ca0 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
37cb0 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
37cc0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
37cd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
37ce0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
37cf0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
37d00 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
37d10 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37  emental I/O {F17
37d20 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  810}.**.** This 
37d30 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
37d40 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65   a handle to the
37d50 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a   blob located.**
37d60 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
37d70 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
37d80 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
37d90 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
37da0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
37db0 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
37dc0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
37dd0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
37de0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
37df0 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
37e00 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
37e10 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
37e20 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
37e30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
37e40 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
37e50 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
37e60 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
37e70 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
37e80 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
37e90 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
37ea0 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
37eb0 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
37ec0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
37ed0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
37ee0 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
37ef0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
37f00 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
37f10 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
37f20 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
37f30 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
37f40 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73  se that.** is as
37f50 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20  signed when the 
37f60 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
37f70 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
37f80 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  ACH]..** For the
37f90 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
37fa0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
37fb0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
37fc0 2e 20 20 46 6f 72 0a 2a 2a 20 54 45 4d 50 20 74  .  For.** TEMP t
37fd0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
37fe0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
37ff0 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  p"..**.** On suc
38000 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
38010 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
38020 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73  d the new .** [s
38030 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
38040 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  ob handle] is wr
38050 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62  itten to *ppBlob
38060 2e 20 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  . .** Otherwise 
38070 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
38080 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a   returned and .*
38090 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74  * any value writ
380a0 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73  ten to *ppBlob s
380b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
380c0 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  d by the caller.
380d0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
380e0 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62  n sets the datab
380f0 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72  ase-handle error
38100 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
38110 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
38120 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
38130 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
38140 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
38150 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
38160 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33  S:.**.** {F17813
38170 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
38180 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
38190 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
381a0 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c  pen(D,B,T,C,R,F,
381b0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
381c0 69 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20  interface opens 
381d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  an [sqlite3_blob
381e0 5d 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68  ] object P on th
381f0 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20  e blob.**       
38200 20 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f     in column C o
38210 66 20 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74  f table T in dat
38220 61 62 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61  abase B on [data
38230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38240 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31   D..**.** {F1781
38250 34 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  4} A successful 
38260 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
38270 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
38280 28 44 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a  (D,...)] starts.
38290 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  **          a ne
382a0 77 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e  w transaction on
382b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
382c0 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74  ction] D if that
382d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
382e0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 61          is not a
382f0 6c 72 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e  lready in a tran
38300 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  saction..**.** {
38310 46 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c  F17816} The [sql
38320 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44  ite3_blob_open(D
38330 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69  ,B,T,C,R,F,P)] i
38340 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 74  nterface opens t
38350 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
38360 20 20 20 20 66 6f 72 20 72 65 61 64 20 61 6e 64      for read and
38370 20 77 72 69 74 65 20 61 63 63 65 73 73 20 69 66   write access if
38380 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
38390 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20   F parameter.** 
383a0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
383b0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  zero..**.** {F17
383c0 38 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  819} The [sqlite
383d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69  3_blob_open()] i
383e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
383f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
38400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63  .**          suc
38410 63 65 73 73 20 61 6e 64 20 61 6e 20 61 70 70 72  cess and an appr
38420 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
38430 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
38440 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 32 31 7d 20  .**.** {F17821} 
38450 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
38460 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
38470 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
38480 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e  _blob_open(D,...
38490 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  )].**          t
384a0 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63  hen subsequent c
384b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
384c0 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a  _errcode(D)],.**
384d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
384e0 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61  e3_errmsg(D)], a
384f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
38500 73 67 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65  sg16(D)] will re
38510 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
38520 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70   information app
38530 72 6f 70 72 61 74 65 20 66 6f 72 20 74 68 61 74  roprate for that
38540 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
38550 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
38560 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
38570 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
38580 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38590 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
385a0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
385b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
385c0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
385d0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
385e0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
385f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c  ** CAPI3REF:  Cl
38600 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
38610 65 20 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a  e {F17830}.**.**
38620 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b   Close an open [
38630 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
38640 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  lob handle]..**.
38650 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  ** Closing a BLO
38660 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
38670 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
38680 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
38690 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
386a0 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
386b0 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
386c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
386d0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
386e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
386f0 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  s in autocommit 
38700 6d 6f 64 65 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  mode..** If any 
38710 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
38720 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
38730 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
38740 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
38750 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
38760 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
38770 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a  ill fit. {END}.*
38780 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  * Closing the BL
38790 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
387a0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
387b0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
387c0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
387d0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
387e0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
387f0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
38800 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
38810 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38  s closed.  {F178
38820 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74  33} Any errors t
38830 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
38840 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
38850 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
38860 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
38870 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42  lue..**.** The B
38880 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e  LOB is closed un
38890 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20  conditionally.  
388a0 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75  Even if this rou
388b0 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  tine returns.** 
388c0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74  an error code, t
388d0 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c  he BLOB is still
388e0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49   closed..**.** I
388f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38900 20 7b 46 31 37 38 33 33 7d 20 54 68 65 20 5b 73   {F17833} The [s
38910 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
38920 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(P)] interface 
38930 63 6c 6f 73 65 73 20 61 6e 0a 2a 2a 20 20 20 20  closes an.**    
38940 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
38950 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 70 72  lob] object P pr
38960 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20  eviously opened 
38970 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
38980 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f    [sqlite3_blob_
38990 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  open()]..**.** {
389a0 46 31 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67 20  F17836} Closing 
389b0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  an [sqlite3_blob
389c0 5d 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 2a  ] objec