/ Hex Artifact Content
Login

Artifact 5956da2f10f6bf7bb008b3932da7921a1b08893f:


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 32 33 20 32 30 30 38 2f  in,v 1.323 2008/
05f0: 30 36 2f 30 39 20 32 31 3a 35 37 3a 32 33 20 64  06/09 21:57:23 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 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1690: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31  ction Handle {F1
16a0: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  2000}.** KEYWORD
16b0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
16c0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
16d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
16e0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1700: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1710: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
1720: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
1730: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
1740: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1750: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1760: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1770: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1780: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1790: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
17a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
17b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
17c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
17d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
17e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
17f0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
1800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1810: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
1820: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
1830: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
1840: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
1850: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1860: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1870: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1880: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1890: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18a0: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
18b0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
18c0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
18d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
18e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
18f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
1900: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1910: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1920: 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d  r Types {F10200}
1930: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1940: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1950: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
1960: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
1970: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
1980: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
1990: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
19a0: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
19b0: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
19c0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
19d0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
19e0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
19f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
1a00: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
1a10: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
1a20: 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20  eferred type.** 
1a30: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68  definitions.  Th
1a40: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
1a50: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
1a60: 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75   types are.** su
1a70: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1a80: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a90: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
1aa0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ab0: 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b  * {F10201} The [
1ac0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
1ad0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
1ae0: 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20  ] types specify 
1af0: 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34  a.**          64
1b00: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1b10: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ger..**.** {F102
1b20: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1b30: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1b40: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1b50: 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  es specify.**   
1b60: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
1b70: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1b80: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
1b90: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
1ba0: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
1bb0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1bc0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
1bd0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
1be0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
1bf0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
1c00: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
1c10: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
1c20: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
1c30: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
1c40: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1c50: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1c60: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
1c70: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
1c80: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
1c90: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
1ca0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1cb0: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
1cc0: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
1cd0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
1ce0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
1cf0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
1d00: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
1d10: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
1d20: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
1d30: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
1d40: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
1d50: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
1d60: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
1d70: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
1d80: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
1d90: 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  int.*/.#ifdef SQ
1da0: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1db0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1dc0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1dd0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1de0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1df0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1e00: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
1e10: 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2010}.**.** This
1e20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
1e30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
1e40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e50: 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70  ect.  .**.** App
1e60: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1e70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e80: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
1e90: 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  ll.** [prepared 
1ea0: 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a  statements] and.
1eb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1ec0: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
1ed0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  all [sqlite3_blo
1ee0: 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61  b | BLOBs] .** a
1ef0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f00: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1f10: 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ect prior.** to 
1f20: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
1f30: 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ose the [sqlite3
1f40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
1f50: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
1f60: 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72  ns to pending tr
1f70: 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65  ansactions?  Are
1f80: 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20   they.** rolled 
1f90: 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e  back, or abandon
1fa0: 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ed?</todo>.**.**
1fb0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fc0: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
1fd0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1fe0: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
1ff0: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
2000: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2010: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2020: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2030: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2040: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2050: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2060: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2070: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2080: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
2090: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20a0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
20b0: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
20c0: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
20d0: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
20e0: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
20f0: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
2100: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2110: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2120: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a  ction contains.*
2130: 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2140: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2150: 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62   that have not b
2160: 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
2170: 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71  finalized by [sq
2180: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2190: 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
21a0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20  _close()].**    
21b0: 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53        returns [S
21c0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
21d0: 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65  leaves the conne
21e0: 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  ction open..**.*
21f0: 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e  * {F12014} Givin
2200: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
2210: 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ) a NULL pointer
2220: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
2230: 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  o-op..**.** LIMI
2240: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
2250: 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61  U12015} The para
2260: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2270: 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20  3_close()] must 
2280: 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  be an [sqlite3] 
2290: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
22a0: 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69     pointer previ
22b0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
22c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
22d0: 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20  n()] or the .** 
22e0: 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c           equival
22f0: 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  ent, or NULL..**
2300: 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65  .** {U12016} The
2310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2320: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
2330: 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2340: 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  en previously.**
2350: 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64            closed
2360: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2370: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2380: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2390: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
23a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
23b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
23c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
23d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2400: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2410: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2420: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2430: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2440: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2450: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2460: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2470: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2480: 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a  erface {F12100}.
2490: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24a0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
24b0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
24c0: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
24d0: 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  g.** one or more
24e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
24f0: 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66  without a lot of
2500: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a   C code.  The.**
2510: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2520: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2530: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
2550: 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65  te3_exec().  The
2560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2570: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2580: 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69   one.** until ei
2590: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72  ther an error or
25a0: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25b0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a   encountered or.
25c0: 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72  ** until they ar
25d0: 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65  e all done.  The
25e0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
25f0: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a  s an optional.**
2600: 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69   callback that i
2610: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
2620: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61  or each row of a
2630: 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ny query results
2640: 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20  .** produced by 
2650: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2660: 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  ts.  The 5th par
2670: 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65  ameter tells whe
2680: 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61  re.** to write a
2690: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
26a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72  s..**.** The err
26b0: 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65  or message passe
26c0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
26d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
26e0: 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d   is held.** in m
26f0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2700: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2710: 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69  loc()].  To avoi
2720: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c  d a memory leak,
2730: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  .** the calling 
2740: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2750: 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ld call [sqlite3
2760: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20  _free()] on any 
2770: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2780: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
2790: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
27a0: 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  ter when it has 
27b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
27c0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
27d0: 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  age..**.** If th
27e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27f0: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2800: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20  eter is NULL or 
2810: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a  an empty string.
2820: 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63  ** or a string c
2830: 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77  ontaining only w
2840: 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f  hitespace and co
2850: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51 4c  mments, then SQL
2860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2870: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2890: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
28a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
28b0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
28c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
28d0: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
28e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28f0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2900: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2910: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2920: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2930: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2940: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2950: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2960: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2970: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2980: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2990: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
29a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
29b0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
29c0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a  INVARIANTS:.** .
29d0: 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75  ** {F12101} A su
29e0: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
29f0: 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2a00: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
2a10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
2a20: 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ll evaluate all 
2a30: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
2a40: 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d  oded, semicolon-
2a50: 73 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20 20  separated,.**   
2a60: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
2a70: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
2a80: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
2a90: 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65  ing S within the
2aa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2ab0: 74 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b 64  text of the D [d
2ac0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ad0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  on]..**.** {F121
2ae0: 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72  02} If the S par
2af0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2b00: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
2b10: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  E)] is NULL then
2b20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2b30: 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20   actions of the 
2b40: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2b50: 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69  be the same as i
2b60: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2b70: 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 68    S parameter wh
2b80: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72  ere an empty str
2b90: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ing..**.** {F121
2ba0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
2bb0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2bc0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
2bd0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  e [SQLITE_OK] if
2be0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2bf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2c00: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79  run successfully
2c10: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69   and to completi
2c20: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  on..**.** {F1210
2c30: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  5} The return va
2c40: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
2c50: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
2c60: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
2c80: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
2c90: 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74  e] if any SQL st
2ca0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a  atement fails..*
2cb0: 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66  *.** {F12107} If
2cc0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2cd0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2ce0: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
2cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
2d00: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2d10: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65   results and the
2d20: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2d30: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
2d40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d50: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2d60: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
2d70: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2d80: 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  r shall be.**   
2d90: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
2da0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2db0: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
2dc0: 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68  * {F12110} If th
2dd0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
2de0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
2df0: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
2e00: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
2e10: 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72        shall abor
2e20: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
2e30: 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e  ent it is curren
2e40: 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a  tly evaluating,.
2e50: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70  **          skip
2e60: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
2e70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  SQL statements, 
2e80: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
2e90: 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2ea0: 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73   {F12113} The [s
2eb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
2ec0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73  outine shall pas
2ed0: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
2ee0: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
2ef0: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
2f00: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
2f10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2f20: 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65  .** {F12116} The
2f30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2f40: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
2f50: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2f60: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
2f70: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
2f80: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
2f90: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2fa0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
2fb0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
2fc0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39  t..**.** {F12119
2fd0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2fe0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2ff0: 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61  ets the 3rd para
3000: 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a  meter of its .**
3010: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3020: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3030: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3040: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3050: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3060: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3070: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3080: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3090: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
30a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
30b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
30c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
30d0: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
30e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
30f0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
3100: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   4th parameter o
3110: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
3120: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
3130: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3140: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3150: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
3160: 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f           names o
3170: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
3180: 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
3190: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
31a0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
31b0: 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65   {F12125} If the
31c0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
31e0: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
31f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3200: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76  ite3_exec()] nev
3210: 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c  er invokes a cal
3220: 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72  lback.  All quer
3230: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
3240: 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74  sults are silent
3250: 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  ly discarded..**
3260: 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20  .** {F12131} If 
3270: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3280: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3290: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
32a0: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
32b0: 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 69 6e         handed in
32c0: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
32d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32e0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e  c(D,S,C,A,E)] an
32f0: 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  d if.**         
3300: 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72   the E parameter
3310: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
3320: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
3330: 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a  ()] shall store.
3340: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a  **          in *
3350: 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  E an appropriate
3360: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77   error message w
3370: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3380: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20  ry obtained.**  
3390: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71          from [sq
33a0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
33b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20  .**.** {F12134} 
33c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
33d0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f  c(D,S,C,A,E)] ro
33e0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
33f0: 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
3400: 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e           *E to N
3410: 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20  ULL if E is not 
3420: 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61  NULL and there a
3430: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  re no errors..**
3440: 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65  .** {F12137} The
3450: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3460: 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74  ,S,C,A,E)] funct
3470: 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ion shall set th
3480: 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
3490: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
34a0: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
34b0: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
34c0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
34d0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
34e0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
34f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3500: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38  ]..**.** {F12138
3510: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3520: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3530: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3540: 5d 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20 65  ] is a null or e
3550: 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mpty.**         
3560: 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61   string or conta
3570: 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65  ins nothing othe
3580: 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
3590: 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e 64  e, comments, and
35a0: 2f 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  /or.**          
35b0: 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e  semicolons, then
35c0: 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c   results of [sql
35d0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
35e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3610: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
3620: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65        shall rese
3630: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f  t to indicate no
3640: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c   errors..**.** L
3650: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3660: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3670: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3680: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3690: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
36a0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
36b0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
36c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
36d0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
36e0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36f0: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3700: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3710: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3720: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3730: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20  running..** .** 
3740: 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {U12143} The cal
3750: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
3760: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
3770: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
3780: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
3790: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
37a0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
37b0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
37c0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
37d0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
37e0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
37f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d  ..**.** {U12145}
3800: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
3810: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
3820: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3830: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3840: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
3850: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
3860: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
3870: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3880: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
3890: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
38a0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
38d0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
38e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
38f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3900: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3910: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
3920: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3930: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3940: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3950: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3960: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3970: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
39a0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
39b0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
39c0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
39f0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3a00: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
3a10: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
3a20: 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45  s {F10210}.** KE
3a30: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
3a40: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
3a50: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a  error codes}.**.
3a60: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
3a70: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
3a80: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
3a90: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
3aa0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3ab0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3ac0: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3ad0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3ae0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
3af0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
3b00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3b10: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
3b20: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3b30: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3b40: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3b50: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3b60: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3b70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b80: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3b90: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3ba0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3bb0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3bc0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3bd0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
3be0: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
3bf0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
3c00: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
3c10: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
3c20: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
3c30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3c40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
3c50: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
3c60: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
3c70: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
3c80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c90: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
3ca0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
3cb0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
3cc0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3cd0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
3ce0: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
3cf0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
3d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
3d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
3d20: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
3d30: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
3d40: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d50: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
3d60: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
3d70: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
3d80: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
3d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3da0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
3db0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
3dc0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
3dd0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
3de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3df0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
3e00: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
3e10: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
3e20: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
3e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
3e40: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
3e50: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
3e60: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
3e70: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
3e80: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
3e90: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
3ea0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
3eb0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
3ee0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
3ef0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
3f00: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
3f10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f20: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
3f30: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
3f40: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
3f50: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3f60: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
3f70: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
3f80: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
3f90: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
3fa0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
3fb0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
3fc0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
3fd0: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
3fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
3ff0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4000: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4010: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4030: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4040: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4050: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4060: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4070: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4080: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4090: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
40a0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
40c0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
40d0: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
40e0: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
40f0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4100: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4110: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4120: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4130: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4140: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4150: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4160: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4170: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4180: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4190: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
41a0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
41b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
41c0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
41d0: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
41e0: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
41f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4200: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4210: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4220: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4230: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4240: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4250: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4260: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4270: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4280: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4290: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42a0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
42b0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
42c0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
42d0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
42e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
42f0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4300: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4310: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4320: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4330: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4340: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4350: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4360: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30  esult Codes {F10
4370: 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  220}.** KEYWORDS
4380: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4390: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
43a0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
43b0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
43c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43d0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
43e0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
43f0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4400: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4410: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4420: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4430: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4440: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4450: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4460: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
4470: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
4480: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4490: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
44a0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
44b0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
44c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
44d0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
44e0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
44f0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4500: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4510: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4520: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4530: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4540: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4550: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4560: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4570: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4580: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4590: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
45a0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
45b0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
45c0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
45d0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
45e0: 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61  d.** for each da
45f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4600: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
4610: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4620: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a  sult_codes()].**
4630: 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d   API..** .** Som
4640: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4650: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4660: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4670: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4680: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4690: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
46a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
46b0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
46c0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
46d0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
46e0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
46f0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4700: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4710: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4720: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4730: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4740: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4750: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4760: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4770: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4780: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4790: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a  tly zero..** .**
47a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
47b0: 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20  ** {F10223} The 
47c0: 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f  symbolic name fo
47d0: 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  r an extended re
47e0: 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73  sult code always
47f0: 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
4800: 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64 20        a related 
4810: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4820: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
4830: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20  .**.** {F10224} 
4840: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  Primary result c
4850: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
4860: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
4870: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
4880: 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {F10225} Extende
4890: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
48a0: 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20  mes contain two 
48b0: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72  or more "_" char
48c0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  acters..**.** {F
48d0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72  10226} The numer
48e0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
48f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4900: 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ode contains the
4910: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
4920: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74  eric value of it
4930: 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  s corresponding 
4940: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4950: 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ode in.**       
4960: 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67     its least sig
4970: 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e  nificant 8 bits.
4980: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4990: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
49a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
49c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
49d0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
49e0: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
49f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
4a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4a10: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
4a20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4a30: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a50: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4a60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4a70: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4a90: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
4aa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4ab0: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ad0: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
4ae0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4af0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
4b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4b10: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
4b20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4b30: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
4b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4b50: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
4b60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b70: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
4b80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b90: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
4ba0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4bb0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
4bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4bd0: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
4be0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4bf0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
4c00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c10: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
4c20: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c30: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c50: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
4c60: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c70: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
4c80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c90: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
4ca0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cb0: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
4cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4cd0: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
4ce0: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
4cf0: 7c 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a  | (14<<8))../*.*
4d00: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
4d10: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
4d20: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32  Operations {F102
4d30: 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  30}.**.** These 
4d40: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
4d50: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
4d60: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
4d70: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
4d80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4d90: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
4da0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
4db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4dc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
4dd0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4de0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
4df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e00: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
4e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e30: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
4e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e60: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
4e70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
4ea0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a  E    0x00000008.
4eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ec0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
4ed0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
4ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ef0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
4f00: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f20: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
4f30: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
4f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f50: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
4f60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f80: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
4f90: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a       0x00000800.
4fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fb0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
4fc0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a       0x00001000.
4fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fe0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
4ff0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
5000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5010: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
5020: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a  AL   0x00004000.
5030: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5040: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5050: 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d  ristics {F10240}
5060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5070: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
5080: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5090: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
50a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
50b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
50c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
50d0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
50e0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
50f0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5100: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5110: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5120: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5130: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5140: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5150: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5160: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5170: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5180: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5190: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
51a0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
51b0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
51c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
51d0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
51e0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
51f0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5200: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5210: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5220: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5230: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5240: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5250: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5260: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5270: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5280: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5290: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
52a0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
52b0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
52c0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
52d0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
52e0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
52f0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5300: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5310: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5320: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5330: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5340: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5350: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5360: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5370: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5380: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5390: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
53a0: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  te()..*/.#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53c0: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78  OMIC          0x
53d0: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
53e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53f0: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78  OMIC512       0x
5400: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
5410: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5420: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78  OMIC1K        0x
5430: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5450: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78  OMIC2K        0x
5460: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5480: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78  OMIC4K        0x
5490: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
54a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54b0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78  OMIC8K        0x
54c0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
54d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54e0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78  OMIC16K       0x
54f0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5510: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78  OMIC32K       0x
5520: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5540: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78  OMIC64K       0x
5550: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5560: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5570: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78  FE_APPEND     0x
5580: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5590: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
55a0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78  QUENTIAL      0x
55b0: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20  00000400../*.** 
55c0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
55d0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46  ocking Levels {F
55e0: 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  10250}.**.** SQL
55f0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5600: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5610: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5620: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5630: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
5640: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
5650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
5660: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
5670: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5680: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
56a0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
56b0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
56c0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
56d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
56e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
56f0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5700: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5710: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5730: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5740: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
5750: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
5760: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
5770: 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68  F10260}.**.** Wh
5780: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5790: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
57a0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
57b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57c0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
57d0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
57e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
57f0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5800: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5810: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5820: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5830: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5840: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5850: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5860: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5870: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5880: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5890: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
58a0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
58b0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68  t be flushed. Th
58c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
58d0: 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20  RMAL flag means 
58e0: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
58f0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
5900: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
5910: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
5920: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
5930: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
5940: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
5950: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5970: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
5980: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
5990: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
59a0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
59b0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
59c0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
59d0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f       0x00010.../
59e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
59f0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5a00: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31   File Handle {F1
5a10: 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  1110}.**.** An [
5a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5a30: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
5a40: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
5a50: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
5a60: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
5a70: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5a80: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
5a90: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
5aa0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
5ab0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
5ac0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
5ad0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
5ae0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
5af0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
5b00: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
5b10: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
5b40: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
5b50: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
5b60: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
5b70: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
5b80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
5b90: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
5ba0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
5bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
5bc0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
5bd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5be0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
5bf0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
5c00: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5c10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5c30: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5c40: 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30  s Object {F11120
5c50: 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  }.**.** Every fi
5c60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
5c70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
5c80: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
5c90: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
5ca0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
5cb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5cc0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
5cd0: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
5ce0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
5cf0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
5d00: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
5d10: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5d20: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5d30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
5d40: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
5d50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5d60: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
5d70: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
5d80: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
5d90: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
5da0: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
5db0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
5dc0: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
5dd0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
5de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
5df0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
5e00: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
5e10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
5e20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
5e30: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
5e40: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
5e50: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
5e60: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5e70: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5e80: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5e90: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5ea0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5eb0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
5ec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5ed0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
5ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5ef0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
5f00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5f10: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5f30: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5f40: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5f50: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5f60: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5f70: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5f80: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
5f90: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5fa0: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
5fb0: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
5fc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5fd0: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
5fe0: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
5ff0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6000: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6010: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
6020: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6030: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6040: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6050: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6060: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6070: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6080: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
6090: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
60a0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
60b0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
60c0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
60d0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
60e0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
60f0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
6100: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
6110: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6120: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
6130: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
6140: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
6150: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
6160: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
6170: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
6180: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6190: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
61a0: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
61b0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
61c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
61d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
61e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
61f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6200: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6210: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6220: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6230: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6240: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6250: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6260: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6270: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6280: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6290: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
62a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
62b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
62c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
62d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
62e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
62f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6300: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6310: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6320: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
6330: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
6340: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
6350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6360: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6370: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6380: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6390: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
63a0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
63b0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
63c0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
63d0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
63e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
63f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6400: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6410: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6420: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6430: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6440: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6450: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6460: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6470: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6480: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6490: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
64a0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
64b0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
64c0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
64d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
64e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
64f0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6500: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6510: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6520: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6530: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6540: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6550: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6560: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6570: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6590: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
65b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
65d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
65f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6600: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6610: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6630: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6640: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6650: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6660: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6670: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6680: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6690: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
66b0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
66c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
66d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
66e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
66f0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6700: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6730: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6740: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6750: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6760: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6770: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6780: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6790: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
67a0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
67b0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
67c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
67d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
67e0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
67f0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6800: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6810: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6820: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6830: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6840: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6850: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6860: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6870: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6880: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6890: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
68a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
68b0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
68c0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
68d0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
68e0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
68f0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6900: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6910: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6920: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6930: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6940: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6950: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6960: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
6970: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
6980: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
6990: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
69a0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
69b0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
69c0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
69d0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
69e0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
69f0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6a00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6a10: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6a20: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6a30: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6a40: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6a50: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6a60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6a70: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6a80: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6a90: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6aa0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6ab0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6ac0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6ad0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6ae0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6af0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6b00: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6b10: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6b20: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
6b30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6b40: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6b50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6b60: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6b70: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6b80: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6ba0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6bb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6bc0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6bd0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6be0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6bf0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6c00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c10: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6c20: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6c30: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6c40: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6c50: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6c60: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6c70: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6c80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6c90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ca0: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6cc0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6cd0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6ce0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6cf0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6d00: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6d10: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6d20: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6d30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6d40: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6d50: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6d60: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6d70: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6d80: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6d90: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6da0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6db0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6dd0: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6de0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6df0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6e00: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6e10: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6e20: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6e30: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6e40: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6e50: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6e60: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6e70: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6e80: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ea0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6eb0: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6ed0: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6ef0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6f00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6f10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6f20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6f30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6f40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6f50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6f60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6f70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6f80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6f90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6fa0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6fb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6fc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6fd0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6fe0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6ff0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
7000: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
7010: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
7020: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7030: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
7040: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
7050: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7060: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
7070: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
7080: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7090: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
70a0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
70b0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
70c0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
70d0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
70e0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
70f0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7100: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7110: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7120: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7130: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7140: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7150: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
7160: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
7170: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
7180: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
7190: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
71a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
71b0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
71c0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
71d0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
71e0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
71f0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7200: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7210: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7220: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7230: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7240: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7250: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7260: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7270: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7280: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7290: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
72a0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
72b0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
72c0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
72d0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
72e0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
72f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7300: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7310: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7320: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7330: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7340: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7350: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7360: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7370: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7380: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7390: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
73a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
73b0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
73c0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
73d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
73e0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
73f0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7400: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7410: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7420: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7430: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7440: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7450: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7460: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7470: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7480: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7490: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
74a0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
74b0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
74c0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
74d0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
74e0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
74f0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7500: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7510: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7520: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7530: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7540: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
7550: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
7560: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7570: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
7580: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
7590: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
75a0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
75b0: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
75c0: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
75d0: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
75e0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
75f0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7600: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7610: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7620: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7630: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7640: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
7650: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
7660: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
7670: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
7680: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
7690: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
76a0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
76b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
76c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
76d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
76e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
76f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7700: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7710: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7720: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7730: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7740: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7750: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
7760: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
7770: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
7780: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
7790: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
77a0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
77b0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
77c0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
77d0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
77e0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
77f0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7800: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7810: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7820: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7830: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7840: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
7850: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
7860: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
7870: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
7880: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
7890: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
78a0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
78b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
78c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
78d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
78e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
78f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7900: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7910: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7920: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7930: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7950: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
7960: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
7970: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
7980: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7990: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
79a0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
79b0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
79c0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
79d0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
79e0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
79f0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7a00: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7a10: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7a20: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7a30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7a40: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7a50: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
7a60: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
7a70: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
7a80: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
7a90: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
7aa0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
7ab0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7ac0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7ad0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7ae0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7af0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7b00: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7b10: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7b20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7b30: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7b40: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
7b50: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7b60: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7b70: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7b80: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7b90: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7ba0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7bb0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7bc0: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7bd0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7be0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7bf0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7c00: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7c10: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7c20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7c30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7c40: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
7c50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7c60: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
7c70: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7c80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7c90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7ca0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7cb0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7cc0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7cd0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7ce0: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7cf0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7d00: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7d10: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7d20: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
7d30: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
7d40: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
7d50: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
7d60: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7d70: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7d80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7d90: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7da0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7db0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7dc0: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7dd0: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7de0: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7df0: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7e00: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7e10: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7e20: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7e30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7e40: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7e50: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7e60: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7e70: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7e80: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7e90: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7ea0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7eb0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7ec0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7ed0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7ee0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7ef0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7f00: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7f10: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f20: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7f30: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7f40: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7f50: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7f60: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
7f70: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7f80: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7f90: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7fa0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7fb0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7fc0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7fd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7fe0: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7ff0: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
8000: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
8010: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
8020: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
8030: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
8040: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
8050: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8060: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8070: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8080: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
8090: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
80a0: 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35  Pathname. {F1115
80b0: 31 7d 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20  1} The exact.** 
80c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
80d0: 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73  ut buffer is als
80e0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
80f0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
8100: 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e  .** methods. {EN
8110: 44 7d 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  D} If the output
8120: 20 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c   buffer is not l
8130: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8140: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 0a 2a  LITE_CANTOPEN].*
8150: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
8160: 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69 73  rned. As this is
8170: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
8180: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
8190: 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c  ite,.** vfs impl
81a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
81b0: 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20 70  ld endeavor to p
81c0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
81d0: 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74  etting .** mxPat
81e0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
81f0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
8200: 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  lue..** .** The 
8210: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8220: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8230: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8240: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8250: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8260: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8270: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8280: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8290: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
82a0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
82b0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
82c0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
82d0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
82e0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
82f0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8300: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8310: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8320: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8330: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8340: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8350: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8360: 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78  ained.  The.** x
8370: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
8380: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
8390: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
83a0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
83b0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
83c0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
83d0: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
83e0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
83f0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
8400: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
8410: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
8420: 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a  te and.** time..
8430: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8440: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
8450: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
8460: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
8470: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
8480: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
8490: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
84a0: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
84b0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
84c0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
84d0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
84e0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
84f0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
8500: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
8510: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
8520: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
8530: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
8540: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
8550: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
8560: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8570: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
8580: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
8590: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
85a0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
85b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
85c0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
85d0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
85e0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
85f0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8600: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8610: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
8620: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
8630: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
8640: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
8650: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
8660: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8670: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8680: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
8690: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
86a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
86b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
86c0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
86d0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86e0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
86f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8710: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
8720: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
8730: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
8740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8750: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
8760: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8770: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8780: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8790: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
87a0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
87b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
87c0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
87d0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
87e0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
87f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
8800: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
8810: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
8820: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8830: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8840: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8850: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8860: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
8870: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
8880: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
8890: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
88a0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
88b0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
88c0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
88d0: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
88e0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
88f0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
8900: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
8910: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
8920: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
8930: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
8940: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
8950: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
8960: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
8970: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31  s VFS method {F1
8980: 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  1190}.**.** {F11
8990: 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67  191} These integ
89a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
89b0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
89c0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
89d0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
89e0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
89f0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
8a00: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
8a10: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
8a20: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8a30: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8a40: 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20  ss method is.** 
8a50: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46  looking for.  {F
8a60: 31 31 31 39 32 7d 20 57 69 74 68 20 5b 53 51 4c  11192} With [SQL
8a70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8a80: 53 5d 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  S], the xAccess 
8a90: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
8aa0: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
8ab0: 66 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  f the file exist
8ac0: 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68  s. {F11193} With
8ad0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53  .** SQLITE_ACCES
8ae0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8af0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8b00: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a  checks to see.**
8b10: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8b20: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
8b30: 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31  d writable.  {F1
8b40: 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51  1194} With.** SQ
8b50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8b60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8b70: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
8b80: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
8b90: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
8ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8bb0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
8bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
8bd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8be0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
8bf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
8c00: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
8c10: 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20 43  PI3REF: SQLite C
8c20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 44 65 66  onfiguration Def
8c30: 69 6e 69 74 69 6f 6e 20 7b 46 31 30 31 38 30 7d  inition {F10180}
8c40: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
8c50: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
8c60: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
8c70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 74 72  onfiguration str
8c80: 75 63 74 75 72 65 0a 2a 2a 20 6d 61 79 20 62 65  ucture.** may be
8c90: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 70 61 73 73   optionally pass
8ca0: 65 64 20 69 6e 74 6f 20 74 68 65 20 5b 73 71 6c  ed into the [sql
8cb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8cc0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
8cd0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 65 74 20  in order to set 
8ce0: 75 70 20 61 20 63 75 73 74 6f 6d 20 63 6f 6e 66  up a custom conf
8cf0: 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
8d00: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
8d10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 65 6d  ..**.** The xMem
8d20: 49 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 69  Init() routine i
8d30: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 70 4d  s called with pM
8d40: 65 6d 43 6c 69 65 6e 74 44 61 74 61 20 61 73 20  emClientData as 
8d50: 61 6e 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 61  an argument.** a
8d60: 74 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  t [sqlite3_initi
8d70: 61 6c 69 7a 65 28 29 5d 2e 20 20 78 4d 65 6d 53  alize()].  xMemS
8d80: 68 75 74 64 6f 77 6e 20 69 73 20 63 61 6c 6c 65  hutdown is calle
8d90: 64 20 61 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  d at .** [sqlite
8da0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
8db0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4d 65 6d  *.** If the xMem
8dc0: 53 69 7a 65 20 70 6f 69 6e 74 65 72 20 6d 61 79  Size pointer may
8dd0: 20 62 65 20 6f 6d 69 74 74 65 64 2c 0a 2a 2a 20   be omitted,.** 
8de0: 62 75 74 20 69 66 20 69 74 20 69 73 2c 20 74 68  but if it is, th
8df0: 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
8e00: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
8e10: 65 73 20 77 69 6c 6c 20 6e 6f 74 20 77 6f 72 6b  es will not work
8e20: 0a 2a 2a 20 63 6f 72 72 65 63 74 6c 79 3a 0a 2a  .** correctly:.*
8e30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8e40: 3e 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  >   [sqlite3_mem
8e50: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 3c  ory_used()].** <
8e60: 6c 69 3e 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d  li>   [sqlite3_m
8e70: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
8e80: 29 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 20 5b 73 71  )].** <li>   [sq
8e90: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
8ea0: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 3c 2f 75 6c  limit()].** </ul
8eb0: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 4d 65 6d 53  >.**.** If xMemS
8ec0: 69 7a 65 20 69 73 20 64 65 66 69 6e 65 64 2c 20  ize is defined, 
8ed0: 74 68 65 6e 20 53 51 4c 69 74 65 20 77 69 6c 6c  then SQLite will
8ee0: 20 68 6f 6c 64 20 74 68 65 0a 2a 2a 20 5b 53 51   hold the.** [SQ
8ef0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
8f00: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 77 69 6c  C_MEM] mutex wil
8f10: 6c 20 61 63 63 65 73 73 69 6e 67 20 61 6e 79 20  l accessing any 
8f20: 6f 66 20 78 4d 65 6d 41 6c 6c 6f 63 2c 0a 2a 2a  of xMemAlloc,.**
8f30: 20 78 4d 65 6d 52 65 61 6c 6c 6f 63 2c 20 6f 72   xMemRealloc, or
8f40: 20 78 4d 65 6d 46 72 65 65 2e 20 20 49 66 20 78   xMemFree.  If x
8f50: 4d 65 6d 53 69 7a 65 20 69 73 20 4e 55 4c 4c 20  MemSize is NULL 
8f60: 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  then the.** [SQL
8f70: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
8f80: 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 69 73 20 6e  _MEM] mutex is n
8f90: 65 76 65 72 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ever used..**.**
8fa0: 20 54 68 65 20 78 50 61 67 65 41 6c 6c 6f 63 20   The xPageAlloc 
8fb0: 61 6e 64 20 78 50 61 67 65 46 72 65 65 20 66 75  and xPageFree fu
8fc0: 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 74 65  nctions are alte
8fd0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 0a  rnative memory .
8fe0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 66 6f  ** allocators fo
8ff0: 72 20 70 61 67 65 20 63 61 63 68 65 20 70 61 67  r page cache pag
9000: 65 73 2e 20 20 49 66 20 75 6e 64 65 66 69 6e 65  es.  If undefine
9010: 64 0a 2a 2a 20 74 68 65 6e 20 78 4d 65 6d 41 6c  d.** then xMemAl
9020: 6c 6f 63 20 61 6e 64 20 78 4d 65 6d 46 72 65 65  loc and xMemFree
9030: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a   will be used..*
9040: 2a 0a 2a 2a 20 54 68 65 20 78 54 65 6d 70 41 6c  *.** The xTempAl
9050: 6c 6f 63 20 61 6e 64 20 78 54 65 6d 70 46 72 65  loc and xTempFre
9060: 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
9070: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
9080: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
9090: 20 66 6f 72 20 73 68 6f 72 74 2d 6c 69 76 65 64   for short-lived
90a0: 20 74 65 6d 70 6f 72 61 72 79 20 73 70 61 63 65   temporary space
90b0: 2e 0a 2a 2a 20 49 66 20 75 6e 64 65 66 69 6e 65  ..** If undefine
90c0: 64 20 74 68 65 6e 20 78 4d 65 6d 41 6c 6c 6f 63  d then xMemAlloc
90d0: 20 61 6e 64 20 78 4d 65 6d 46 72 65 65 20 61 62   and xMemFree ab
90e0: 6f 76 65 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ove will be used
90f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 6e 65 20 6f 66 20  ..**.** None of 
9100: 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
9110: 74 65 6d 20 66 69 65 6c 64 73 20 61 72 65 20 65  tem fields are e
9120: 76 65 72 20 61 63 63 65 73 73 65 64 0a 2a 2a 20  ver accessed.** 
9130: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
9140: 70 69 6c 65 64 20 77 69 74 68 20 2d 44 53 51 4c  piled with -DSQL
9150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
9160: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
9170: 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 69  exInit routine i
9180: 73 20 63 61 6c 6c 65 64 20 62 79 20 65 61 63 68  s called by each
9190: 20 65 66 66 65 63 74 69 76 65 20 5b 73 71 6c 69   effective [sqli
91a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
91b0: 5d 0a 2a 2a 20 61 6e 64 20 78 4d 75 74 65 78 53  ].** and xMutexS
91c0: 68 75 74 64 6f 77 6e 20 69 73 20 63 61 6c 6c 65  hutdown is calle
91d0: 64 20 62 79 20 65 61 63 68 20 76 61 6c 69 64 20  d by each valid 
91e0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
91f0: 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 62  n()]..**.** If b
9200: 53 65 72 69 61 6c 69 7a 65 43 6f 6e 6e 65 63 74  SerializeConnect
9210: 69 6f 6e 20 69 73 20 74 72 75 65 20 74 68 65 6e  ion is true then
9220: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
9230: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
9240: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45  [SQLITE_MUTEX_RE
9250: 43 55 52 53 49 56 45 5d 20 6d 75 74 65 78 65 73  CURSIVE] mutexes
9260: 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 63   to serialize ac
9270: 63 65 73 73 20 74 6f 20 0a 2a 2a 20 5b 64 61 74  cess to .** [dat
9280: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9290: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
92a0: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
92b0: 74 73 2e 20 20 49 66 0a 2a 2a 20 62 53 65 72 69  ts.  If.** bSeri
92c0: 61 6c 69 7a 65 43 6f 6e 6e 65 63 74 69 6f 6e 20  alizeConnection 
92d0: 69 73 20 66 61 6c 73 65 2c 20 74 68 65 6e 20 69  is false, then i
92e0: 74 20 69 73 20 74 68 65 20 61 70 70 6c 69 63 61  t is the applica
92f0: 74 69 6f 6e 27 73 0a 2a 2a 20 72 65 73 70 6f 6e  tion's.** respon
9300: 73 69 62 69 69 6c 69 74 79 20 74 6f 20 73 65 72  sibiility to ser
9310: 69 61 6c 69 7a 65 20 61 63 63 65 73 73 20 74 6f  ialize access to
9320: 20 74 68 65 73 65 20 6f 62 6a 65 63 74 73 2e 0a   these objects..
9330: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78  **.** The xMutex
9340: 54 72 79 20 69 6e 74 65 72 66 61 63 65 20 69 73  Try interface is
9350: 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
9360: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
9370: 2a 20 63 6f 6d 65 20 75 70 20 6f 66 74 65 6e 20  * come up often 
9380: 61 6e 64 20 63 61 6e 20 62 65 20 6f 6d 69 74 74  and can be omitt
9390: 65 64 2e 20 20 49 66 20 6f 6d 69 74 74 65 64 2c  ed.  If omitted,
93a0: 20 78 4d 75 74 65 78 45 6e 74 65 72 0a 2a 2a 20   xMutexEnter.** 
93b0: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 69 6e 20  will be used in 
93c0: 69 74 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  its place..**.**
93d0: 20 54 68 65 20 78 4d 75 74 65 78 48 65 6c 64 20   The xMutexHeld 
93e0: 61 6e 64 20 78 4d 75 74 65 78 4e 6f 74 48 65 6c  and xMutexNotHel
93f0: 64 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  d interfaces are
9400: 20 75 73 65 64 20 66 6f 72 20 74 65 73 74 69 6e   used for testin
9410: 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 20 6f 6e  g.** purposes on
9420: 6c 79 2e 20 20 49 74 20 69 73 20 6f 6b 20 66 6f  ly.  It is ok fo
9430: 72 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  r these function
9440: 73 20 74 6f 20 72 65 70 6f 72 74 20 66 61 6c 73  s to report fals
9450: 65 0a 2a 2a 20 70 6f 73 69 74 69 76 65 73 2e 20  e.** positives. 
9460: 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
9470: 20 61 72 65 20 6f 6e 6c 79 20 75 73 65 64 20 77   are only used w
9480: 69 74 68 69 6e 20 74 68 65 20 61 72 67 75 6d 65  ithin the argume
9490: 6e 74 20 6f 66 0a 2a 2a 20 61 73 73 65 72 74 28  nt of.** assert(
94a0: 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2f  ) statements..*/
94b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
94c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72  sqlite3_configur
94d0: 61 74 69 6f 6e 20 73 71 6c 69 74 65 33 5f 63 6f  ation sqlite3_co
94e0: 6e 66 69 67 75 72 61 74 69 6f 6e 3b 0a 73 74 72  nfiguration;.str
94f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  uct sqlite3_conf
9500: 69 67 75 72 61 74 69 6f 6e 20 7b 0a 20 20 2f 2a  iguration {.  /*
9510: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
9520: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 74  on subsystem int
9530: 65 72 66 61 63 65 20 2a 2f 0a 20 20 76 6f 69 64  erface */.  void
9540: 20 2a 70 4d 65 6d 43 6c 69 65 6e 74 44 61 74 61   *pMemClientData
9550: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ;             /*
9560: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 4d 65   Argument to xMe
9570: 6d 49 6e 69 74 20 61 6e 64 20 78 4d 65 6d 53 68  mInit and xMemSh
9580: 75 74 64 6f 77 6e 20 2a 2f 0a 20 20 69 6e 74 20  utdown */.  int 
9590: 28 2a 78 4d 65 6d 49 6e 69 74 29 28 76 6f 69 64  (*xMemInit)(void
95a0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
95b0: 20 4d 61 79 20 62 65 20 4e 55 4c 4c 20 2a 2f 0a   May be NULL */.
95c0: 20 20 69 6e 74 20 28 2a 78 4d 65 6d 53 68 75 74    int (*xMemShut
95d0: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
95e0: 20 20 20 20 2f 2a 20 4d 61 79 20 62 65 20 4e 55      /* May be NU
95f0: 4c 4c 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  LL */.  void *(*
9600: 78 4d 65 6d 41 6c 6c 6f 63 29 28 69 6e 74 29 3b  xMemAlloc)(int);
9610: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 65 6d 52  .  void *(*xMemR
9620: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 20 69  ealloc)(void*, i
9630: 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
9640: 65 6d 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 0a  emFree)(void*);.
9650: 20 20 69 6e 74 20 28 2a 78 4d 65 6d 53 69 7a 65    int (*xMemSize
9660: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
9670: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 79 20           /* May 
9680: 62 65 20 4e 55 4c 4c 20 2a 2f 0a 20 20 2f 2a 20  be NULL */.  /* 
9690: 41 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  Alternative memo
96a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 66 6f  ry allocators fo
96b0: 72 20 70 61 67 65 20 63 61 63 68 65 20 61 6e 64  r page cache and
96c0: 20 74 72 61 6e 73 69 65 6e 74 20 73 74 6f 72 61   transient stora
96d0: 67 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  ge */.  void *(*
96e0: 78 50 61 67 65 41 6c 6c 6f 63 29 28 69 6e 74 20  xPageAlloc)(int 
96f0: 69 53 69 7a 65 29 3b 20 20 20 20 20 20 20 20 2f  iSize);        /
9700: 2a 20 4d 61 79 20 62 65 20 4e 55 4c 4c 20 2a 2f  * May be NULL */
9710: 0a 20 20 76 6f 69 64 20 28 2a 78 50 61 67 65 46  .  void (*xPageF
9720: 72 65 65 29 28 76 6f 69 64 2a 2c 20 69 6e 74 20  ree)(void*, int 
9730: 69 53 69 7a 65 29 3b 20 20 20 2f 2a 20 4d 61 79  iSize);   /* May
9740: 20 62 65 20 4e 55 4c 4c 20 2a 2f 0a 20 20 76 6f   be NULL */.  vo
9750: 69 64 20 2a 28 2a 78 54 65 6d 70 41 6c 6c 6f 63  id *(*xTempAlloc
9760: 29 28 69 6e 74 20 69 53 69 7a 65 29 3b 20 20 20  )(int iSize);   
9770: 20 20 20 20 20 2f 2a 20 4d 61 79 20 62 65 20 4e       /* May be N
9780: 55 4c 4c 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ULL */.  void (*
9790: 78 54 65 6d 70 46 72 65 65 29 28 76 6f 69 64 2a  xTempFree)(void*
97a0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  );              
97b0: 2f 2a 20 4d 61 79 20 62 65 20 4e 55 4c 4c 20 2a  /* May be NULL *
97c0: 2f 0a 20 20 2f 2a 20 50 61 72 61 6d 65 74 65 72  /.  /* Parameter
97d0: 73 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 75 73 65  s optionally use
97e0: 64 20 62 79 20 73 6f 6d 65 20 61 6c 74 65 72 6e  d by some altern
97f0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  ative memory all
9800: 6f 63 61 74 6f 72 73 2e 20 2a 2f 0a 20 20 73 71  ocators. */.  sq
9810: 6c 69 74 65 33 5f 69 6e 74 36 34 20 6e 4d 65 6d  lite3_int64 nMem
9820: 48 65 61 70 3b 20 20 20 20 20 20 2f 2a 20 54 6f  Heap;      /* To
9830: 74 61 6c 20 6d 65 6d 6f 72 79 20 61 76 61 69 6c  tal memory avail
9840: 61 62 6c 65 20 66 6f 72 20 61 6c 6c 6f 63 61 74  able for allocat
9850: 69 6e 67 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ing */.  void *p
9860: 4d 65 6d 48 65 61 70 3b 20 20 20 20 20 20 20 20  MemHeap;        
9870: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9880: 20 74 6f 20 6d 65 6d 6f 72 79 20 73 70 61 63 65   to memory space
9890: 20 74 6f 20 62 65 20 61 6c 6c 6f 63 61 74 65 64   to be allocated
98a0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 6e 4d 65 6d 41   */.  int mnMemA
98b0: 6c 6c 6f 63 3b 20 20 20 20 20 20 20 20 20 20 20  lloc;           
98c0: 20 20 20 2f 2a 20 4d 69 6e 69 6d 75 6d 20 61 6c     /* Minimum al
98d0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
98e0: 0a 20 20 69 6e 74 20 6d 78 4d 65 6d 41 6c 6c 6f  .  int mxMemAllo
98f0: 63 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c;              
9900: 2f 2a 20 4d 61 78 69 6d 75 6d 20 61 6c 6c 6f 63  /* Maximum alloc
9910: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
9920: 69 6e 74 20 6e 54 65 6d 70 3b 20 20 20 20 20 20  int nTemp;      
9930: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
9940: 4d 61 78 69 6d 75 6d 20 74 65 6d 70 20 73 70 61  Maximum temp spa
9950: 63 65 20 61 76 61 69 6c 61 62 6c 65 20 2a 2f 0a  ce available */.
9960: 20 20 69 6e 74 20 6d 78 54 65 6d 70 3b 20 20 20    int mxTemp;   
9970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
9980: 2a 20 4d 61 78 69 6d 75 6d 20 74 65 6d 70 20 73  * Maximum temp s
9990: 70 61 63 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  pace allocation 
99a0: 73 69 7a 65 20 2a 2f 0a 20 20 2f 2a 20 4d 75 74  size */.  /* Mut
99b0: 65 78 20 6d 65 74 68 6f 64 73 20 2a 2f 0a 20 20  ex methods */.  
99c0: 76 6f 69 64 20 2a 70 4d 75 74 65 78 43 6c 69 65  void *pMutexClie
99d0: 6e 74 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ntData;         
99e0: 20 20 20 2f 2a 20 41 72 67 20 74 6f 20 78 4d 75     /* Arg to xMu
99f0: 74 65 78 49 6e 69 74 20 61 6e 64 20 78 4d 75 74  texInit and xMut
9a00: 65 78 53 68 75 74 64 6f 77 6e 20 2a 2f 0a 20 20  exShutdown */.  
9a10: 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74  int (*xMutexInit
9a20: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
9a30: 20 20 20 2f 2a 20 4d 61 79 20 62 65 20 4e 55 4c     /* May be NUL
9a40: 4c 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4d 75  L */.  int (*xMu
9a50: 74 65 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  texShutdown)(voi
9a60: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 4d 61 79  d*);      /* May
9a70: 20 62 65 20 4e 55 4c 4c 20 2a 2f 0a 20 20 69 6e   be NULL */.  in
9a80: 74 20 62 53 65 72 69 61 6c 69 7a 65 43 6f 6e 6e  t bSerializeConn
9a90: 65 63 74 69 6f 6e 3b 0a 20 20 73 71 6c 69 74 65  ection;.  sqlite
9aa0: 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 65  3_mutex *(*xMute
9ab0: 78 41 6c 6c 6f 63 29 28 69 6e 74 20 6d 75 74 65  xAlloc)(int mute
9ac0: 78 54 79 70 65 29 3b 0a 20 20 76 6f 69 64 20 28  xType);.  void (
9ad0: 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c  *xMutexFree)(sql
9ae0: 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 20 20  ite3_mutex*);.  
9af0: 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74  void (*xMutexEnt
9b00: 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  er)(sqlite3_mute
9b10: 78 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  x*);.  int (*xMu
9b20: 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f  texTry)(sqlite3_
9b30: 6d 75 74 65 78 2a 29 3b 20 20 20 20 20 20 20 2f  mutex*);       /
9b40: 2a 20 4d 61 79 20 62 65 20 4e 55 4c 4c 20 2a 2f  * May be NULL */
9b50: 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
9b60: 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d  Leave)(sqlite3_m
9b70: 75 74 65 78 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  utex*);.  int (*
9b80: 78 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69  xMutexHeld)(sqli
9b90: 74 65 33 5f 6d 75 74 65 78 2a 29 3b 20 20 20 20  te3_mutex*);    
9ba0: 20 20 2f 2a 20 4d 61 79 20 62 65 20 4e 55 4c 4c    /* May be NULL
9bb0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74   */.  int (*xMut
9bc0: 65 78 4e 6f 74 48 65 6c 64 29 28 73 71 6c 69 74  exNotHeld)(sqlit
9bd0: 65 33 5f 6d 75 74 65 78 2a 29 3b 20 20 20 2f 2a  e3_mutex*);   /*
9be0: 20 4d 61 79 20 62 65 20 4e 55 4c 4c 20 2a 2f 0a   May be NULL */.
9bf0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
9c00: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
9c10: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9c20: 79 20 7b 46 31 30 31 34 30 7d 0a 2a 2a 0a 2a 2a  y {F10140}.**.**
9c30: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9c40: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
9c50: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
9c60: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a 2a  nitialize the.**
9c70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
9c80: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e    The sqlite3_in
9c90: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
9ca0: 6e 65 20 69 73 20 6f 6e 6c 79 20 65 66 66 65 63  ne is only effec
9cb0: 74 69 76 65 0a 2a 2a 20 74 68 65 20 66 69 72 73  tive.** the firs
9cc0: 74 20 74 69 6d 65 20 69 74 20 69 73 20 63 61 6c  t time it is cal
9cd0: 6c 65 64 20 77 69 74 68 69 6e 20 61 20 70 72 6f  led within a pro
9ce0: 63 65 73 73 2c 20 6f 72 20 74 68 65 20 66 69 72  cess, or the fir
9cf0: 73 74 20 74 69 6d 65 20 69 74 0a 2a 2a 20 69 73  st time it.** is
9d00: 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 61 20   called after a 
9d10: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9d20: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 74 68  shutdown().  Oth
9d30: 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 0a 2a  er SQLite APIs.*
9d40: 2a 20 6d 69 67 68 74 20 69 6e 76 6f 6b 65 20 73  * might invoke s
9d50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9d60: 65 28 29 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  e() internally, 
9d70: 73 6f 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 0a  so in order for.
9d80: 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
9d90: 6e 20 74 6f 20 62 65 20 73 75 72 65 20 74 68 61  n to be sure tha
9da0: 74 20 69 74 73 20 63 61 6c 6c 20 74 6f 20 73 71  t its call to sq
9db0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9dc0: 28 29 0a 2a 2a 20 69 73 20 66 69 72 73 74 2c 20  ().** is first, 
9dd0: 69 74 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  it should invoke
9de0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9df0: 69 7a 65 28 29 20 70 72 69 6f 72 20 74 6f 20 69  ize() prior to i
9e00: 6e 76 6f 6b 69 6e 67 20 61 6e 79 0a 2a 2a 20 6f  nvoking any.** o
9e10: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9e20: 72 66 61 63 65 20 28 77 69 74 68 20 74 68 65 20  rface (with the 
9e30: 70 6f 73 73 69 62 6c 65 20 65 78 63 65 70 74 69  possible excepti
9e40: 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
9e50: 5f 64 65 66 61 75 6c 74 5f 63 6f 6e 66 69 67 75  _default_configu
9e60: 72 61 74 69 6f 6e 28 29 20 61 73 20 64 65 73 63  ration() as desc
9e70: 72 69 62 65 64 20 62 65 6c 6f 77 2e 29 0a 2a 2a  ribed below.).**
9e80: 0a 2a 2a 20 49 66 20 74 68 65 20 70 61 72 61 6d  .** If the param
9e90: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
9ea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9eb0: 4e 55 4c 4c 20 74 68 65 6e 20 61 20 64 65 66 61  NULL then a defa
9ec0: 75 6c 74 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ult.** configura
9ed0: 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41  tion is used.  A
9ee0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 65 66   copy of the def
9ef0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
9f00: 6f 6e 20 63 61 6e 0a 2a 2a 20 62 65 20 6f 62 74  on can.** be obt
9f10: 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  ained using the 
9f20: 73 71 6c 69 74 65 33 5f 64 65 66 61 75 6c 74 5f  sqlite3_default_
9f30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 28 29 20  configuration() 
9f40: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 6e  interface..** An
9f50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
9f60: 74 20 6f 6e 6c 79 20 77 61 6e 74 73 20 74 6f 20  t only wants to 
9f70: 6d 61 6b 65 20 73 6c 69 67 68 74 20 61 64 6a 75  make slight adju
9f80: 73 74 6d 65 6e 74 73 20 74 6f 20 74 68 65 0a 2a  stments to the.*
9f90: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
9fa0: 63 61 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  can invoke sqlit
9fb0: 65 33 5f 64 65 66 61 75 6c 74 5f 63 6f 6e 66 69  e3_default_confi
9fc0: 67 75 72 61 74 69 6f 6e 28 29 20 74 6f 20 70 6f  guration() to po
9fd0: 70 75 6c 61 74 65 0a 2a 2a 20 61 6e 20 69 6e 69  pulate.** an ini
9fe0: 74 69 61 6c 6c 79 20 65 6d 70 74 79 20 5b 73 71  tially empty [sq
9ff0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72 61 74  lite3_configurat
a000: 69 6f 6e 5d 20 73 74 72 75 63 74 75 72 65 2c 20  ion] structure, 
a010: 6d 61 6b 65 20 77 68 61 74 65 76 65 72 0a 2a 2a  make whatever.**
a020: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74   changes to that
a030: 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 64   structure are d
a040: 65 73 69 72 65 64 2c 20 74 68 65 6e 20 69 6e 76  esired, then inv
a050: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
a060: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 74 6f 20 72  ialize().** to r
a070: 65 67 69 73 74 65 72 20 74 68 65 20 6e 65 77 20  egister the new 
a080: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e 20 20  configuration.  
a090: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a0a0: 65 33 5f 64 65 66 61 75 6c 74 5f 63 6f 6e 66 69  e3_default_confi
a0b0: 67 75 72 61 74 69 6f 6e 28 29 20 69 6e 74 65 72  guration() inter
a0c0: 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 69 6e  face does not in
a0d0: 76 6f 6b 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33  voke .** sqlite3
a0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
a0f0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
a100: 63 61 6e 20 63 61 6c 6c 0a 2a 2a 20 73 71 6c 69  can call.** sqli
a110: 74 65 33 5f 64 65 66 61 75 6c 74 5f 63 6f 6e 66  te3_default_conf
a120: 69 67 75 72 61 74 69 6f 6e 28 29 20 62 65 66 6f  iguration() befo
a130: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  re sqlite3_initi
a140: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 74 69 6c  alize() and stil
a150: 6c 0a 2a 2a 20 62 65 20 61 73 73 75 72 65 64 20  l.** be assured 
a160: 74 68 61 74 20 69 74 73 20 63 61 6c 6c 20 74 6f  that its call to
a170: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a180: 69 7a 65 28 29 20 69 73 20 74 68 65 20 66 69 72  ize() is the fir
a190: 73 74 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 66 69  st..** The confi
a1a0: 67 75 72 61 74 69 6f 6e 20 72 65 74 75 72 6e 65  guration returne
a1b0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 65 66  d by sqlite3_def
a1c0: 61 75 6c 74 5f 63 6f 6e 66 69 67 75 72 61 74 69  ault_configurati
a1d0: 6f 6e 28 29 20 69 73 0a 2a 2a 20 61 20 63 6f 6d  on() is.** a com
a1e0: 70 69 6c 65 64 2d 69 6e 20 64 65 66 61 75 6c 74  piled-in default
a1f0: 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20  .  Changing the 
a200: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
a210: 69 6e 67 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f  ing a call.** to
a220: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a230: 69 7a 65 28 29 20 64 6f 65 73 20 6e 6f 74 20 63  ize() does not c
a240: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
a250: 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73  returned by.** s
a260: 71 6c 69 74 65 33 5f 64 65 66 61 75 6c 74 5f 63  qlite3_default_c
a270: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 28 29 2e 20  onfiguration(). 
a280: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 65 66   The sqlite3_def
a290: 61 75 6c 74 5f 63 6f 6e 66 69 67 75 72 61 74 69  ault_configurati
a2a0: 6f 6e 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  on().** interfac
a2b0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
a2c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
a2d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  d parameter to b
a2e0: 6f 74 68 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oth sqlite3_init
a2f0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
a300: 73 71 6c 69 74 65 33 5f 64 65 66 61 75 6c 74 5f  sqlite3_default_
a310: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 28 29 20  configuration() 
a320: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 62 65  should always be
a330: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 56   the.** SQLITE_V
a340: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 63 6f  ERSION_NUMBER co
a350: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 63 6f 6e  nstant.  The con
a360: 74 65 6e 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tent of the.** [
a370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72  sqlite3_configur
a380: 61 74 69 6f 6e 5d 20 73 74 72 75 63 74 75 72 65  ation] structure
a390: 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66   may change in f
a3a0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
a3b0: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  f.** SQLite and 
a3c0: 73 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  so the sqlite3_i
a3d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
a3e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 65 66 61  .** sqlite3_defa
a3f0: 75 6c 74 5f 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult_configuratio
a400: 6e 28 29 29 20 66 75 6e 63 74 69 6f 6e 73 20 6e  n()) functions n
a410: 65 65 64 20 74 6f 20 6b 6e 6f 77 20 74 68 65 0a  eed to know the.
a420: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
a430: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 68  e header file th
a440: 61 74 20 64 65 66 69 6e 65 64 20 74 68 65 20 5b  at defined the [
a450: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72  sqlite3_configur
a460: 61 74 69 6f 6e 5d 0a 2a 2a 20 73 74 72 75 63 74  ation].** struct
a470: 75 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ure in order to 
a480: 75 73 65 20 74 68 65 20 73 74 72 75 63 74 75 72  use the structur
a490: 65 20 63 6f 72 72 65 63 74 6c 79 2e 0a 2a 2a 0a  e correctly..**.
a4a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
a4b0: 65 66 61 75 6c 74 5f 63 6f 6e 66 69 67 75 72 61  efault_configura
a4c0: 74 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  tion() interface
a4d0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
a4e0: 4f 4b 20 6f 6e 0a 2a 2a 20 73 75 63 63 65 73 73  OK on.** success
a4f0: 2e 20 20 49 66 20 74 68 65 20 69 56 65 72 73 69  .  If the iVersi
a500: 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  on parameter is 
a510: 73 75 63 68 20 74 68 61 74 20 53 51 4c 69 74 65  such that SQLite
a520: 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f   is unable.** to
a530: 20 66 69 6c 6c 20 69 6e 20 74 68 65 20 5b 73 71   fill in the [sq
a540: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72 61 74  lite3_configurat
a550: 69 6f 6e 5d 20 73 74 72 75 63 74 75 72 65 2c 20  ion] structure, 
a560: 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
a570: 63 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ce.** will retur
a580: 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  n SQLITE_ERROR..
a590: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
a5a0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
a5b0: 65 20 74 68 61 74 20 74 68 65 20 69 6e 69 74 69  e that the initi
a5c0: 61 6c 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  al call to sqlit
a5d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
a5e0: 2a 2a 20 69 73 20 73 65 72 69 61 6c 69 7a 65 64  ** is serialized
a5f0: 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
a600: 61 74 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65  at multi-threade
a610: 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  d applications s
a620: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 0a 2a 2a 20  hould invoke.** 
a630: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a640: 7a 65 28 29 20 69 6e 20 74 68 65 20 6d 61 69 6e  ze() in the main
a650: 20 74 68 72 65 61 64 20 70 72 69 6f 72 20 74 6f   thread prior to
a660: 20 73 74 61 72 74 69 6e 67 20 61 6e 79 20 6f 74   starting any ot
a670: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 74  her.** threads t
a680: 68 61 74 20 6d 69 67 68 74 20 75 73 65 20 53 51  hat might use SQ
a690: 4c 69 74 65 2e 20 20 49 6e 20 74 68 65 20 67 65  Lite.  In the ge
a6a0: 6e 65 72 61 6c 20 63 61 73 65 2c 20 53 51 4c 69  neral case, SQLi
a6b0: 74 65 20 64 65 70 65 6e 64 73 20 6f 6e 0a 2a 2a  te depends on.**
a6c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a6d0: 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 63   to serialize ac
a6e0: 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  cess to sqlite3_
a6f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 62 65 63  initialize() bec
a700: 61 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63  ause SQLite.** c
a710: 61 6e 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6d  annot create a m
a720: 75 74 65 78 20 74 6f 20 64 6f 20 74 68 65 20 73  utex to do the s
a730: 65 72 69 61 6c 69 7a 61 74 69 6f 6e 20 69 74 73  erialization its
a740: 65 6c 66 20 75 6e 74 69 6c 20 61 66 74 65 72 0a  elf until after.
a750: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
a760: 61 6c 69 7a 65 28 29 20 68 61 73 20 72 75 6e 2e  alize() has run.
a770: 20 20 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74    In the current
a780: 20 75 6e 69 78 20 61 6e 64 20 77 69 6e 33 32 0a   unix and win32.
a790: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a7a0: 6e 73 2c 20 53 51 4c 69 74 65 20 69 73 20 61 62  ns, SQLite is ab
a7b0: 6c 65 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20  le to serialize 
a7c0: 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
a7d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
a7e0: 2a 20 6f 6e 20 69 74 73 20 6f 77 6e 2c 20 62 75  * on its own, bu
a7f0: 74 20 74 68 69 73 20 69 73 20 6e 6f 74 20 74 72  t this is not tr
a800: 75 65 20 66 6f 72 20 61 6c 6c 20 65 6d 62 65 64  ue for all embed
a810: 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 61 6e  ded platforms an
a820: 64 20 6d 69 67 68 74 0a 2a 2a 20 6e 6f 74 20 62  d might.** not b
a830: 65 20 74 72 75 65 20 66 6f 72 20 75 6e 69 78 20  e true for unix 
a840: 61 6e 64 20 77 69 6e 33 32 20 69 6e 20 66 75 74  and win32 in fut
a850: 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
a860: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
a870: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
a880: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
a890: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72 61  qlite3_configura
a8a0: 74 69 6f 6e 5d 20 73 74 72 75 63 74 75 72 65 0a  tion] structure.
a8b0: 2a 2a 20 74 68 61 74 20 69 73 20 70 61 73 73 65  ** that is passe
a8c0: 64 20 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f 69  d into sqlite3_i
a8d0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 48 65  nitialize().  He
a8e0: 6e 63 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  nce the applicat
a8f0: 69 6f 6e 20 69 73 20 66 72 65 65 0a 2a 2a 20 74  ion is free.** t
a900: 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 20  o deallocate or 
a910: 6d 6f 64 69 66 79 20 74 68 65 20 5b 73 71 6c 69  modify the [sqli
a920: 74 65 33 5f 63 6f 6e 66 69 67 75 72 61 74 69 6f  te3_configuratio
a930: 6e 5d 20 73 74 72 75 63 74 75 72 65 20 61 66 74  n] structure aft
a940: 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  er.** sqlite3_in
a950: 69 74 69 61 6c 69 7a 65 28 29 20 72 65 74 75 72  itialize() retur
a960: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 73  ns..**.** Once s
a970: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a980: 65 28 29 20 68 61 73 20 62 65 65 6e 20 73 75 63  e() has been suc
a990: 63 65 73 73 66 75 6c 6c 79 20 69 6e 76 6f 6b 65  cessfully invoke
a9a0: 64 20 6f 6e 63 65 2c 20 61 6c 6c 0a 2a 2a 20 73  d once, all.** s
a9b0: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
a9c0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 61 72 65 20 69 67 6e 6f  alize() are igno
a9e0: 72 65 64 20 75 6e 74 69 6c 0a 2a 2a 20 73 71 6c  red until.** sql
a9f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
aa00: 69 73 20 72 75 6e 2e 20 20 41 66 74 65 72 20 73  is run.  After s
aa10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
aa20: 29 20 68 61 73 20 62 65 65 6e 20 69 6e 76 6f 6b  ) has been invok
aa30: 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 65 78 74 20  ed,.** the next 
aa40: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
aa50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
aa60: 65 66 66 65 63 74 69 76 65 20 66 6f 72 20 61 20  effective for a 
aa70: 73 69 6e 67 6c 65 20 63 61 6c 6c 0a 2a 2a 20 62  single call.** b
aa80: 75 74 20 61 66 74 65 72 20 74 68 61 74 20 73 71  ut after that sq
aa90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
aaa0: 28 29 20 61 67 61 69 6e 20 62 65 63 6f 6d 65 73  () again becomes
aab0: 20 61 20 6e 6f 2d 75 70 2e 20 20 49 6e 20 6f 74   a no-up.  In ot
aac0: 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 61 20  her words,.** a 
aad0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
aae0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
aaf0: 6f 6e 6c 79 20 65 66 66 65 63 74 69 76 65 20 69  only effective i
ab00: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ab10: 74 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  t.** invocation 
ab20: 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 20  for the process 
ab30: 6f 72 20 69 66 20 69 74 20 69 73 20 69 6e 76 6f  or if it is invo
ab40: 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ked immediately 
ab50: 61 66 74 65 72 20 61 0a 2a 2a 20 63 61 6c 6c 20  after a.** call 
ab60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ab70: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  own()..**.** The
ab80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ab90: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
aba0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20  turns SQLITE_OK 
abb0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49  on success..** I
abc0: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
abd0: 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 20 61  lize() returns a
abe0: 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
abf0: 68 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 68  han SQLITE_OK th
ac00: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
ac10: 20 6c 69 62 72 61 72 79 20 69 73 20 6e 6f 74 20   library is not 
ac20: 73 61 66 65 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a  safe to use..**.
ac30: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
ac40: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
ac50: 61 63 65 20 63 6c 65 61 72 73 20 61 20 70 72 69  ace clears a pri
ac60: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  or initializatio
ac70: 6e 20 61 6e 64 0a 2a 2a 20 65 6e 61 62 6c 65 73  n and.** enables
ac80: 20 53 51 4c 69 74 65 20 74 6f 20 62 65 20 72 65   SQLite to be re
ac90: 69 6e 69 74 69 61 6c 69 7a 65 64 2e 20 20 54 68  initialized.  Th
aca0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
acb0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 0a 2a  st insure that.*
acc0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  * the sqlite3_sh
acd0: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ace0: 63 65 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  ce is only calle
acf0: 64 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  d when there are
ad00: 20 6e 6f 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69   no.** outstandi
ad10: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
ad20: 74 69 6f 6e 73 20 6f 72 20 6d 75 74 65 78 65 73  tions or mutexes
ad30: 2c 20 6e 6f 20 6f 70 65 6e 20 64 61 74 61 62 61  , no open databa
ad40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a  se connections,.
ad50: 2a 2a 20 61 6e 64 20 6e 6f 20 6f 74 68 65 72 20  ** and no other 
ad60: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
ad70: 73 20 61 72 65 20 62 65 69 6e 67 20 63 61 6c 6c  s are being call
ad80: 65 64 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  ed in different 
ad90: 74 68 72 65 61 64 73 2e 0a 2a 2a 20 49 66 20 73  threads..** If s
ada0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
adb0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 68 69 6c  ) is called whil
adc0: 65 20 74 68 65 72 65 20 61 72 65 20 73 74 69 6c  e there are stil
add0: 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a  l outstanding.**
ade0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
adf0: 6f 6e 73 20 6f 72 20 6d 75 74 65 78 65 73 2c 20  ons or mutexes, 
ae00: 6f 72 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  or open database
ae10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 6f 72   connections, or
ae20: 20 77 68 69 6c 65 0a 2a 2a 20 61 6e 6f 74 68 65   while.** anothe
ae30: 72 20 74 68 72 65 61 64 20 69 73 20 6d 61 6b 69  r thread is maki
ae40: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 61 6e 79  ng a call to any
ae50: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
ae60: 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 72  e, then the.** r
ae70: 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
ae80: 65 64 20 61 6e 64 20 63 6f 75 6c 64 20 62 65 20  ed and could be 
ae90: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
aea0: 6c 74 20 6f 72 20 6f 74 68 65 72 0a 2a 2a 20 66  lt or other.** f
aeb0: 61 74 61 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  atal application
aec0: 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 41 73   error..**.** As
aed0: 20 63 75 72 72 65 6e 74 6c 79 20 69 6d 70 6c 65   currently imple
aee0: 6d 65 6e 74 65 64 2c 20 73 71 6c 69 74 65 33 5f  mented, sqlite3_
aef0: 73 68 75 74 64 6f 77 6e 28 29 20 61 6c 77 61 79  shutdown() alway
af00: 73 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  s returns SQLITE
af10: 5f 4f 4b 2c 0a 2a 2a 20 68 6f 77 65 76 65 72 20  _OK,.** however 
af20: 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
af30: 65 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  e in a future re
af40: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
af50: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69  .** .** The sqli
af60: 74 65 33 5f 6f 6e 5f 73 68 75 74 64 6f 77 6e 28  te3_on_shutdown(
af70: 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
af80: 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
af90: 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a   to be invoked.*
afa0: 2a 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20  * the next time 
afb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
afc0: 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 45  () is called.  E
afd0: 61 63 68 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ach callback is 
afe0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 6f 6e 6c 79 20  invoked.** only 
aff0: 6f 6e 63 65 20 61 74 20 74 68 65 20 6e 65 78 74  once at the next
b000: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b010: 6e 28 29 20 63 61 6c 6c 2e 20 20 43 61 6c 6c 62  n() call.  Callb
b020: 61 63 6b 73 20 6d 75 73 74 20 62 65 0a 2a 2a 20  acks must be.** 
b030: 72 65 72 65 67 69 73 74 65 72 65 64 20 69 6e 20  reregistered in 
b040: 6f 72 64 65 72 20 74 6f 20 62 65 20 72 75 6e 20  order to be run 
b050: 6f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 73 71  on subsequent sq
b060: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b070: 20 63 61 6c 6c 73 2e 0a 2a 2a 20 45 61 63 68 20   calls..** Each 
b080: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b090: 6f 6e 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 6c  on_shutdown() al
b0a0: 6c 6f 63 61 74 65 73 20 61 20 6c 69 74 74 6c 65  locates a little
b0b0: 20 62 69 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a   bit of memory.*
b0c0: 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
b0d0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
b0e0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 61 6e 64  tion pointer and
b0f0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
b100: 6e 67 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ng.** applicatio
b110: 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
b120: 20 54 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 66   The memory is f
b130: 72 65 65 64 20 61 66 74 65 72 20 74 68 65 20 63  reed after the c
b140: 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 69 6e  allback is.** in
b150: 76 6f 6b 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  voked.  The call
b160: 62 61 63 6b 73 20 72 65 67 69 73 74 65 72 65 64  backs registered
b170: 20 62 79 20 73 71 6c 69 74 65 33 5f 6f 6e 5f 63   by sqlite3_on_c
b180: 61 6c 6c 62 61 63 6b 28 29 20 61 72 65 20 69 6e  allback() are in
b190: 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20  voked.** in the 
b1a0: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 20 74  order in which t
b1b0: 68 65 79 20 77 65 72 65 20 72 65 67 69 73 74 65  hey were registe
b1c0: 72 65 64 2e 20 20 49 66 20 74 68 65 20 73 61 6d  red.  If the sam
b1d0: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  e callback is.**
b1e0: 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
b1f0: 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 74 20 69  iple times, it i
b200: 73 20 69 6e 76 6f 6b 65 64 20 6d 75 6c 74 69 70  s invoked multip
b210: 6c 65 20 74 69 6d 65 73 2e 20 20 41 6c 6c 20 63  le times.  All c
b220: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 61 72 65 20  allbacks.** are 
b230: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
b240: 20 74 68 65 20 78 4d 65 6d 53 68 75 74 64 6f 77   the xMemShutdow
b250: 6e 28 29 20 61 6e 64 20 78 4d 75 74 65 78 53 68  n() and xMutexSh
b260: 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64 73  utdown() methods
b270: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
b280: 65 33 5f 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e3_configuration
b290: 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 0a 2a   structure..**.*
b2a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 6e  * The sqlite3_on
b2b0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
b2c0: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 51  rface returns SQ
b2d0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
b2e0: 73 73 2c 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  ss, or.** SQLITE
b2f0: 5f 4e 4f 4d 45 4d 20 69 66 20 69 74 20 69 73 20  _NOMEM if it is 
b300: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
b310: 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
b320: 64 20 74 68 65 20 70 6f 69 6e 74 65 72 0a 2a 2a  d the pointer.**
b330: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
b340: 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20 63 6f   function and co
b350: 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 70 70 6c  rresponding appl
b360: 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
b370: 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
b380: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b390: 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 63 6f  const sqlite3_co
b3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 2a 2c 20 69 6e  nfiguration*, in
b3b0: 74 20 69 56 65 72 73 69 6f 6e 29 3b 0a 69 6e 74  t iVersion);.int
b3c0: 20 73 71 6c 69 74 65 33 5f 64 65 66 61 75 6c 74   sqlite3_default
b3d0: 5f 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 28 73  _configuration(s
b3e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 75 72 61  qlite3_configura
b3f0: 74 69 6f 6e 2a 2c 20 69 6e 74 20 69 56 65 72 73  tion*, int iVers
b400: 69 6f 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ion);.int sqlite
b410: 33 5f 6f 6e 5f 73 68 75 74 64 6f 77 6e 28 76 6f  3_on_shutdown(vo
b420: 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  id (*)(void*), v
b430: 6f 69 64 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  oid*);.int sqlit
b440: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
b450: 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
b460: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
b470: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
b480: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31  Result Codes {F1
b490: 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2200}.**.** The 
b4a0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
b4b0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
b4c0: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
b4d0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
b4e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
b4f0: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
b500: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
b510: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
b520: 2e 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65  ..** The extende
b530: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
b540: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
b550: 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
b560: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
b570: 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  bility..**.** IN
b580: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
b590: 7b 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65  {F12201} Each ne
b5a0: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
b5b0: 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61  ection] shall ha
b5c0: 76 65 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ve the .**      
b5d0: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65      [extended re
b5e0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
b5f0: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
b600: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
b610: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
b620: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
b630: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
b640: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
b650: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61  erface shall ena
b660: 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
b670: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
b680: 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20   codes] for the 
b690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
b6a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b6b0: 6e 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61  n] D if the F pa
b6c0: 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
b6d0: 20 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20      is true, or 
b6e0: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
b6f0: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
b700: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
b710: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
b720: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
b730: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
b740: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
b750: 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32  ert Rowid {F1222
b760: 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  0}.**.** Each en
b770: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
b780: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
b790: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
b7a0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
b7b0: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
b7c0: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
b7d0: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
b7e0: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
b7f0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
b800: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
b810: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
b820: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
b830: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
b840: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
b850: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
b860: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
b870: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
b880: 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45  umn of type INTE
b890: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
b8a0: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
b8b0: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
b8c0: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
b8d0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
b8e0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
b8f0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
b900: 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
b910: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
b920: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
b930: 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61  se from the data
b940: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
b950: 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20  ** shown in the 
b960: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
b970: 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75   If no successfu
b980: 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76  l inserts.** hav
b990: 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
b9a0: 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65  on this database
b9b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
b9c0: 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
b9d0: 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52  *.** If an INSER
b9e0: 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  T occurs within 
b9f0: 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
ba00: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
ba10: 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77  .** inserted row
ba20: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
ba30: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
ba40: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
ba50: 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ger.** is runnin
ba60: 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65  g.  But once the
ba70: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
ba80: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
ba90: 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68  eturned.** by th
baa0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
bab0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
bac0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
bad0: 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67  fore the.** trig
bae0: 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a  ger fired..**.**
baf0: 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20   An INSERT that 
bb00: 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
bb10: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
bb20: 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
bb30: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72  successful inser
bb40: 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  t and does not c
bb50: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
bb60: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
bb70: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
bb80: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
bb90: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
bba0: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
bbb0: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
bbc0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
bbd0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
bbe0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
bbf0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
bc00: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
bc10: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
bc20: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
bc30: 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65  OR REPLACE .** e
bc40: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
bc50: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
bc60: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
bc70: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
bc80: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
bc90: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
bca0: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
bcb0: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
bcc0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
bcd0: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
bce0: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
bcf0: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
bd00: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
bd10: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
bd20: 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ce. .**.** For t
bd30: 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
bd40: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
bd50: 69 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64  insert is consid
bd60: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
bd70: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
bd80: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
bd90: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
bda0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
bdb0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31  S:.**.** {F12221
bdc0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
bdd0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
bde0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
bdf0: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
be00: 20 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68       rowid of th
be10: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
be20: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20  ccessful insert 
be30: 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  done.**         
be40: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
be50: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
be60: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20   and within the 
be70: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
be80: 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c   or higher level
be90: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
bea0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
beb0: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
bec0: 20 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c      been no qual
bed0: 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a  ifying inserts..
bee0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54  **.** {F12223} T
bef0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
bf00: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
bf10: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
bf20: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61  s.**          sa
bf30: 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61  me value when ca
bf40: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
bf50: 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  me trigger conte
bf60: 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  xt.**          i
bf70: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
bf80: 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f  e and after a RO
bf90: 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49  LLBACK..**.** LI
bfa0: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
bfb0: 20 7b 55 31 32 32 33 32 7d 20 49 66 20 61 20 73   {U12232} If a s
bfc0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 64  eparate thread d
bfd0: 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74  oes a new insert
bfe0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
bff0: 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
c000: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
c010: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
c020: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
c030: 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  d()].**         
c040: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
c050: 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
c060: 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
c070: 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20  nsert rowid,.** 
c080: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
c090: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
c0a0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
c0b0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
c0c0: 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
c0d0: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
c0e0: 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
c0f0: 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
c100: 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
c110: 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e           last in
c120: 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73  sert rowid..*/.s
c130: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
c140: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
c150: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
c160: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c170: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
c180: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
c190: 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a  fied {F12240}.**
c1a0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
c1b0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
c1c0: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
c1d0: 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
c1e0: 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
c1f0: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
c200: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
c210: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
c220: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
c230: 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74  * on the connect
c240: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
c250: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
c260: 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63  eter.  Only.** c
c270: 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
c280: 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
c290: 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ed by the INSERT
c2a0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20  , UPDATE, or.** 
c2b0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
c2c0: 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
c2d0: 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
c2e0: 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
c2f0: 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63  iggers are not c
c300: 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20  ounted. Use the 
c310: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
c320: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
c330: 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  on.** to find th
c340: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
c350: 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64  f changes includ
c360: 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
c370: 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a  ed by triggers..
c380: 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61  **.** A "row cha
c390: 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
c3a0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
c3b0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
c3c0: 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
c3d0: 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
c3e0: 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
c3f0: 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
c400: 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
c410: 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
c420: 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  s of REPLACE con
c430: 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
c440: 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
c450: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
c460: 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f  g, DROP TABLE, o
c470: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
c480: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
c490: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
c4a0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
c4b0: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
c4c0: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
c4d0: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
c4e0: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
c4f0: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
c500: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
c510: 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53  trigger.  Most S
c520: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
c530: 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
c540: 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
c550: 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
c560: 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
c570: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
c580: 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
c590: 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
c5a0: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
c5b0: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
c5c0: 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
c5d0: 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
c5e0: 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
c5f0: 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
c600: 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
c610: 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
c620: 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
c630: 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** Calling [sqli
c640: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
c650: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
c660: 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
c670: 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
c680: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
c690: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  text..**.** This
c6a0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
c6b0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
c6c0: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
c6d0: 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
c6e0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
c6f0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
c700: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
c710: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
c720: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
c730: 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63  .**.** So when c
c740: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
c750: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
c760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
c770: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
c780: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
c790: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
c7a0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
c7b0: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
c7c0: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
c7d0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a  he top level..**
c7e0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
c7f0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 74   of a trigger, t
c800: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
c810: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  es() interface.*
c820: 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  * can be called 
c830: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
c840: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
c850: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
c860: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
c870: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
c880: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
c890: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
c8a0: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
c8b0: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
c8c0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
c8d0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
c8e0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e 20   not include in 
c8f0: 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
c900: 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
c910: 20 73 69 6e 63 65 20 74 68 65 79 20 68 61 76 65   since they have
c920: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
c930: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
c940: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
c950: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
c960: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
c970: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
c980: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
c990: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
c9a0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
c9b0: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
c9c0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20  ster than going 
c9d0: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
c9e0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
c9f0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
ca00: 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65  e.** table.)  Be
ca10: 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70  cause of this op
ca20: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
ca30: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  deletions in.** 
ca40: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
ca50: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
ca60: 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c  changes and will
ca70: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 0a   not be counted.
ca80: 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ** by the sqlite
ca90: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
caa0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
cab0: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
cac0: 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e  ns..** To get an
cad0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
cae0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
caf0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
cb00: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
cb10: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
cb20: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
cb30: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
cb40: 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20  ** {F12241} The 
cb50: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
cb60: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
cb70: 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75  ll return the nu
cb80: 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
cb90: 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20      row changes 
cba0: 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f  caused by the mo
cbb0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
cbc0: 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20  , UPDATE,.**    
cbd0: 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20        or DELETE 
cbe0: 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
cbf0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
cc00: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a  onnection and.**
cc10: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e            within
cc20: 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67   the same or hig
cc30: 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74  her trigger cont
cc40: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
cc50: 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20  there have.**   
cc60: 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
cc70: 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72  any qualifying r
cc80: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
cc90: 2a 20 7b 46 31 32 32 34 33 7d 20 53 74 61 74 65  * {F12243} State
cca0: 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  ments of the for
ccb0: 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  m "DELETE FROM t
ccc0: 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e  ablename" with n
ccd0: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48  o.**          WH
cce0: 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c  ERE clause shall
ccf0: 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65 6e   cause subsequen
cd00: 74 20 63 61 6c 6c 73 20 74 6f 20 0a 2a 2a 20 20  t calls to .**  
cd10: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
cd20: 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
cd30: 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
cd40: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
cd50: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
cd60: 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
cd70: 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
cd80: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
cd90: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
cda0: 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
cdb0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
cdc0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
cdd0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
cde0: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
cdf0: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
ce00: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
ce10: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
ce20: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
ce30: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
ce40: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
ce50: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
ce60: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
ce70: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
ce80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
ce90: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
cea0: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
ceb0: 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a  d {F12260}.***.*
cec0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
ced0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
cee0: 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
cef0: 73 20 63 61 75 73 65 64 0a 2a 2a 20 62 79 20 49  s caused.** by I
cf00: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
cf10: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
cf20: 74 73 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ts since the dat
cf30: 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20  abase handle.** 
cf40: 77 61 73 20 6f 70 65 6e 65 64 2e 20 20 54 68 65  was opened.  The
cf50: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
cf60: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
cf70: 20 61 6c 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20   all trigger.** 
cf80: 63 6f 6e 74 65 78 74 73 2e 20 20 42 75 74 20 74  contexts.  But t
cf90: 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
cfa0: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
cfb0: 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70  s used to.** imp
cfc0: 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63  lement REPLACE c
cfd0: 6f 6e 73 74 72 61 69 6e 74 73 2c 20 64 6f 20 72  onstraints, do r
cfe0: 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
cff0: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a  T processing,.**
d000: 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70   or DROP table p
d010: 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68  rocessing..** Th
d020: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65  e changes.** are
d030: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
d040: 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
d050: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
d060: 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a  m is completed .
d070: 2a 2a 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ** (when the sta
d080: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
d090: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
d0a0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
d0b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
d0c0: 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
d0d0: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
d0e0: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
d0f0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
d100: 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  e" without.** a 
d110: 57 48 45 52 45 20 63 6c 61 75 73 65 20 62 79 20  WHERE clause by 
d120: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
d130: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
d140: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
d150: 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e  h.** faster than
d160: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
d170: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
d180: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
d190: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
d1a0: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
d1b0: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
d1c0: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
d1d0: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
d1e0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
d1f0: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
d200: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
d210: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
d220: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
d230: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
d240: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
d250: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
d260: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
d270: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
d280: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
d290: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
d2a0: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
d2b0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
d2c0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
d2d0: 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  s()] interface..
d2e0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
d2f0: 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31  :.** .** {F12261
d300: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
d310: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
d320: 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
d330: 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
d340: 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
d350: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
d360: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
d370: 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
d380: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
d390: 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
d3a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d3b0: 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
d3c0: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
d3d0: 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
d3e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
d3f0: 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20  nection was.**  
d400: 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64 2e          created.
d410: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 33 7d 20  .**.** {F12263} 
d420: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
d430: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
d440: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
d450: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
d460: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
d470: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65  shall not change
d480: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d490: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
d4a0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  by [sqlite3_tota
d4b0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 0a  l_changes()].**.
d4c0: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
d4d0: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49  **.** {U12264} I
d4e0: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
d4f0: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
d500: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
d510: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d520: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
d530: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
d540: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
d550: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
d560: 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20  e value .**     
d570: 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73       returned is
d580: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
d590: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
d5a0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
d5b0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d5c0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
d5d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
d5e0: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
d5f0: 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32  ning Query {F122
d600: 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  70}.**.** This f
d610: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
d620: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
d630: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
d640: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
d650: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
d660: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
d670: 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
d680: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
d690: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
d6a0: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
d6b0: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
d6c0: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
d6d0: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
d6e0: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
d6f0: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
d700: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
d710: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
d720: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
d730: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
d740: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
d750: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
d760: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
d770: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
d780: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
d790: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
d7a0: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
d7b0: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
d7c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
d7d0: 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  h a database con
d7e0: 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20  nection that.** 
d7f0: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
d800: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
d810: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
d820: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
d830: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73 20  ** If an SQL is 
d840: 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
d850: 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
d860: 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   when sqlite3_in
d870: 74 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 20  terrupt().** is 
d880: 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
d890: 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
d8a0: 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f  n opportunity to
d8b0: 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 2e   be interrupted.
d8c0: 0a 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f 6e  .** It might con
d8d0: 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
d8e0: 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f  ion..** An SQL o
d8f0: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
d900: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
d910: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
d920: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20  ITE_INTERRUPT]. 
d930: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
d940: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
d950: 6e 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52  n is an.** INSER
d960: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
d970: 4c 45 54 45 20 74 68 61 74 20 69 73 20 69 6e 73  LETE that is ins
d980: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
d990: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a  transaction, .**
d9a0: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
d9b0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c   transaction wil
d9c0: 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
d9d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
d9e0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
d9f0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
da00: 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
da10: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
da20: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
da30: 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  rted after sqlit
da40: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
da50: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  eturns..**.** IN
da60: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
da70: 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71  {F12271} The [sq
da80: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
da90: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
daa0: 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e  l force all runn
dab0: 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
dac0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
dad0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
dae0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
daf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
db00: 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20          to halt 
db10: 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
db20: 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
db30: 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a  itional row of.*
db40: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 2e  *          data.
db50: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20  .**.** {F12272} 
db60: 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
db70: 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  t that is interr
db80: 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  upted by [sqlite
db90: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
dba0: 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
dbb0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
dbc0: 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a  NTERRUPT]..**.**
dbd0: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
dbe0: 0a 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66 20  .** {U12279} If 
dbf0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
dc00: 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
dc10: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
dc20: 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20  terrupt()].**   
dc30: 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e         is runnin
dc40: 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
dc50: 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
dc60: 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
dc70: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
dc80: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
dc90: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
dca0: 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
dcb0: 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
dcc0: 70 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a  plete {F10510}.*
dcd0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
dce0: 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66  nes are useful f
dcf0: 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  or command-line 
dd00: 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
dd10: 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
dd20: 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
dd30: 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
dd40: 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c  m complete a SQL
dd50: 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
dd60: 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
dd70: 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
dd80: 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
dd90: 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
dda0: 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
ddb0: 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  g.  These routin
ddc0: 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  es return true i
ddd0: 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
dde0: 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
ddf0: 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
de00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41  QL statement.  A
de10: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
de20: 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
de30: 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
de40: 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
de50: 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
de60: 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f  not a fragment o
de70: 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52  f a.** CREATE TR
de80: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
de90: 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61    Semicolons tha
dea0: 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
deb0: 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
dec0: 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
ded0: 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
dee0: 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
def0: 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
df00: 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
df10: 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
df20: 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
df30: 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
df40: 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
df50: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
df60: 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
df70: 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
df80: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
df90: 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
dfa0: 53 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69  SQL and.** so wi
dfb0: 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
dfc0: 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
dfd0: 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
dfe0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
dff0: 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20  ** {F10511} The 
e000: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
e010: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
e020: 6f 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63  omplete16() func
e030: 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tions.**        
e040: 20 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e    return true (n
e050: 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20  on-zero) if and 
e060: 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74  only if the last
e070: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
e080: 2d 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b 65  -whitespace toke
e090: 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74  n in their input
e0a0: 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20   is a semicolon 
e0b0: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
e0c0: 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65   is not in betwe
e0d0: 65 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64  en the BEGIN and
e0e0: 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45   END of a CREATE
e0f0: 20 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20 20   TRIGGER.**     
e100: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a       statement..
e110: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
e120: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32  S:.**.** {U10512
e130: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73  } The input to s
e140: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
e150: 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ) must be a zero
e160: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
e170: 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
e180: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30  ring..**.** {U10
e190: 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74  513} The input t
e1a0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  o sqlite3_comple
e1b0: 74 65 31 36 28 29 20 6d 75 73 74 20 62 65 20 61  te16() must be a
e1c0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
e1d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
e1e0: 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
e1f0: 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
e200: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e210: 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
e220: 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
e230: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
e240: 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
e250: 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
e260: 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
e270: 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
e280: 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
e290: 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a  rrors {F12310}.*
e2a0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
e2b0: 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63  e identifies a c
e2c0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
e2d0: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a 2a   that might be.*
e2e0: 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  * invoked whenev
e2f0: 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  er an attempt is
e300: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
e310: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a  database table .
e320: 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  ** that another 
e330: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
e340: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
e350: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
e360: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
e370: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
e380: 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
e390: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
e3a0: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
e3b0: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
e3c0: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
e3d0: 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  lock..** If the 
e3e0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
e3f0: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
e400: 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  the.** callback 
e410: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
e420: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
e430: 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73  ts.  The.** firs
e440: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
e450: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
e460: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
e470: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
e480: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
e490: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
e4a0: 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65  routine.  The se
e4b0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
e4c0: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
e4d0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
e4e0: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
e4f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
e500: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
e510: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
e520: 67 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74 68  g event.   If th
e530: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
e540: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
e550: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
e560: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
e570: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
e580: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
e590: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
e5a0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
e5b0: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
e5c0: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  rned..** If the 
e5d0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
e5e0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
e5f0: 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
e600: 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
e610: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
e620: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
e630: 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
e640: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
e650: 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
e660: 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
e670: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a   guarantee that.
e680: 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  ** it will be in
e690: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65  voked when there
e6a0: 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
e6b0: 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ion..** If SQLit
e6c0: 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
e6d0: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
e6e0: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  usy handler coul
e6f0: 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61  d result in.** a
e700: 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
e710: 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
e720: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
e730: 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  USY] or.** [SQLI
e740: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
e750: 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
e760: 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73  oking the.** bus
e770: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
e780: 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
e790: 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
e7a0: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
e7b0: 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
e7c0: 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
e7d0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
e7e0: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
e7f0: 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
e800: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
e810: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
e820: 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
e830: 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
e840: 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
e850: 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
e860: 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
e870: 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
e880: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
e890: 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
e8a0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
e8b0: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
e8c0: 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
e8d0: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
e8e0: 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
e8f0: 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
e900: 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
e910: 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
e920: 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
e930: 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
e940: 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
e950: 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
e960: 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
e970: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
e980: 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
e990: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
e9a0: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
e9b0: 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
e9c0: 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
e9d0: 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
e9e0: 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
e9f0: 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
ea00: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
ea10: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
ea20: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ea30: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
ea40: 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
ea50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
ea60: 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
ea70: 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
ea80: 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
ea90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
eaa0: 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
eab0: 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
eac0: 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
ead0: 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
eae0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
eaf0: 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
eb00: 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
eb10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
eb20: 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
eb30: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
eb40: 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
eb50: 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
eb60: 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
eb70: 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
eb80: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
eb90: 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
eba0: 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
ebb0: 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
ebc0: 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
ebd0: 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
ebe0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
ebf0: 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
ec00: 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
ec10: 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
ec20: 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
ec30: 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
ec40: 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
ec50: 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
ec60: 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
ec70: 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
ec80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
ec90: 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
eca0: 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
ecb0: 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
ecc0: 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
ecd0: 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
ece0: 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
ecf0: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
ed00: 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73  w.sqlite.org/cvs
ed10: 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
ed20: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
ed30: 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
ed40: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
ed50: 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
ed60: 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
ed70: 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
ed80: 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
ed90: 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68  rtant..**..** Th
eda0: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
edb0: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
edc0: 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
edd0: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  r each database.
ede0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
edf0: 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
ee00: 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
ee10: 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f  s any previous o
ee20: 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ne. .** Note tha
ee30: 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
ee40: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
ee50: 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  )] will also set
ee60: 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65   or clear.** the
ee70: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
ee80: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
ee90: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20  .**.** {F12311} 
eea0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  The [sqlite3_bus
eeb0: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e  y_handler()] fun
eec0: 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
eed0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  he busy handler.
eee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
eef0: 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74 61  back in the data
ef00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ef10: 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
ef20: 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  e 1st.**        
ef30: 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
ef40: 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
ef50: 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20 62  ler identified b
ef60: 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33 72  y the 2nd and 3r
ef70: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  d.**          pa
ef80: 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
ef90: 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65 66  {F12312} The def
efa0: 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c 65  ault busy handle
efb0: 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62 61  r for new databa
efc0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69  se connections i
efd0: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s NULL..**.** {F
efe0: 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
eff0: 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 65  or more database
f000: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72   connection shar
f010: 65 20 61 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  e a [sqlite3_ena
f020: 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
f030: 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d   | common cache]
f040: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
f050: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
f060: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
f070: 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
f080: 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
f090: 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
f0a0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
f0b0: 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
f0c0: 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
f0d0: 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20  .** {F12316} If 
f0e0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
f0f0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
f100: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
f110: 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  QLite.**        
f120: 20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74    interface that
f130: 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
f140: 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c  cking event will
f150: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
f160: 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59      [SQLITE_BUSY
f170: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38  ]..**.** {F12318
f180: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
f190: 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68  vokes the busy h
f1a0: 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20  andler with two 
f1b0: 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68 0a  arguments which.
f1c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
f1d0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f  a copy of the po
f1e0: 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62  inter supplied b
f1f0: 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  y the 3rd parame
f200: 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
f210: 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
f220: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20  _handler()] and 
f230: 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  a count of the n
f240: 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a  umber of prior.*
f250: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63  *          invoc
f260: 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  ations of the bu
f270: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
f280: 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
f290: 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  event..**.** LIM
f2a0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
f2b0: 7b 55 31 32 33 31 39 7d 20 41 20 62 75 73 79 20  {U12319} A busy 
f2c0: 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e  handler should n
f2d0: 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68  ot call close th
f2e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f2f0: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
f300: 20 20 6f 72 20 70 72 65 70 61 72 65 64 20 73 74    or prepared st
f310: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 76  atement that inv
f320: 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
f330: 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
f340: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
f350: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
f360: 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
f370: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
f380: 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
f390: 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32  usy Timeout {F12
f3a0: 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  340}.**.** This 
f3b0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
f3c0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
f3d0: 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
f3e0: 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65  ler].** that sle
f3f0: 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20  eps for a while 
f400: 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20  when a.** table 
f410: 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20  is locked.  The 
f420: 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65  handler will sle
f430: 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
f440: 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c  s until .** at l
f450: 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
f460: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
f470: 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e  ng have been don
f480: 65 2e 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65  e. {F12343} Afte
f490: 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73  r.** "ms" millis
f4a0: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
f4b0: 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20  ng, the handler 
f4c0: 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a  returns 0 which.
f4d0: 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ** causes [sqlit
f4e0: 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
f4f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
f500: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
f510: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
f520: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
f530: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
f540: 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
f550: 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
f560: 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
f570: 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
f580: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
f590: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
f5a0: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
f5b0: 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
f5c0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
f5d0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20  connection.  If 
f5e0: 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
f5f0: 64 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64  dler was defined
f600: 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71    .** (using [sq
f610: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
f620: 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
f630: 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
f640: 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
f650: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
f660: 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
f670: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
f680: 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68  *.** {F12341} Th
f690: 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
f6a0: 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
f6b0: 69 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e  ion overrides an
f6c0: 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  y prior.**      
f6d0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
f6e0: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20  y_timeout()] or 
f6f0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
f700: 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67  ndler()] setting
f710: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
f720: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
f730: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
f740: 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20  .** {F12343} If 
f750: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
f760: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
f770: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
f780: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
f790: 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
f7a0: 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
f7b0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
f7c0: 73 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61  s cleared so tha
f7d0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  t.**          al
f7e0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63  l subsequent loc
f7f0: 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65  king events imme
f800: 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b  diately return [
f810: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
f820: 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20  .** {F12344} If 
f830: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
f840: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
f850: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
f860: 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20   a positive.**  
f870: 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e          number N
f880: 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61  , then a busy ha
f890: 6e 64 6c 65 72 20 69 73 20 73 65 74 20 74 68 61  ndler is set tha
f8a0: 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c  t repeatedly cal
f8b0: 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
f8c0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
f8d0: 6f 64 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e  od in the VFS in
f8e0: 74 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69  terface until ei
f8f0: 74 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20  ther the.**     
f900: 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73       lock clears
f910: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75   or until the cu
f920: 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74  mulative sleep t
f930: 69 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ime reported bac
f940: 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  k.**          by
f950: 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64   xSleep() exceed
f960: 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  s N milliseconds
f970: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f980: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
f990: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
f9a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f9b0: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
f9c0: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
f9d0: 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33  ng Queries {F123
f9e0: 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  70}.**.** Defini
f9f0: 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
fa00: 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
fa10: 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
fa20: 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
fa30: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
fa40: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
fa50: 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
fa60: 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
fa70: 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
fa80: 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
fa90: 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
faa0: 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
fab0: 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
fac0: 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
fad0: 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
fae0: 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
faf0: 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
fb00: 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
fb10: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
fb20: 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
fb30: 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
fb40: 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
fb50: 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
fb60: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
fb70: 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
fb80: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
fb90: 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
fba0: 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
fbb0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
fbc0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
fbd0: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
fbe0: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 28 4e  s.  There are (N
fbf0: 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
fc00: 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a  n the array.  .*
fc10: 2a 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f  * The first M po
fc20: 69 6e 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20  inters point to 
fc30: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
fc40: 73 74 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a  strings that .**
fc50: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
fc60: 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
fc70: 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
fc80: 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
fc90: 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
fca0: 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a  esults.  NULL.**
fcb0: 20 76 61 6c 75 65 73 20 61 72 65 20 67 69 76 65   values are give
fcc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
fcd0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
fce0: 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65  es are in.** the
fcf0: 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
fd00: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
fd10: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
fd20: 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
fd30: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
fd40: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
fd50: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
fd60: 69 67 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66  ight consists of
fd70: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
fd80: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
fd90: 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
fda0: 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
fdb0: 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
fdc0: 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
fdd0: 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
fde0: 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
fdf0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fe00: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
fe10: 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
fe20: 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
fe30: 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
fe40: 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
fe50: 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
fe60: 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
fe70: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
fe80: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
fe90: 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
fea0: 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
feb0: 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
fec0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
fed0: 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
fee0: 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
fef0: 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
ff00: 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
ff10: 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
ff20: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
ff30: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
ff40: 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
ff50: 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
ff60: 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
ff70: 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
ff80: 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
ff90: 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
ffa0: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
ffb0: 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
ffc0: 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
ffd0: 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
ffe0: 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
fff0: 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
10000 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
10010 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
10020 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
10030 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
10040 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
10050 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
10060 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
10070 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
10080 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10090 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
100a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
100b0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
100c0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
100d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
100e0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
100f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
10100 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
10110 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10120 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
10130 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
10140 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
10150 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10160 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
10170 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
10180 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
10190 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
101a0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
101b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
101c0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
101d0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
101e0 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
101f0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
10200 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
10210 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
10220 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
10230 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
10240 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
10250 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
10260 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
10270 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73  t should .** pas
10280 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  s the pointer to
10290 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
102a0 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  e to sqlite3_fre
102b0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
102c0 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
102d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
102e0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
102f0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
10300 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  way the .** [sql
10310 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
10320 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
10330 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10340 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
10350 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
10360 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
10370 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10380 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
10390 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72   .** [sqlite3_fr
103a0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
103b0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
103c0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
103d0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
103e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
103f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
10400 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
10410 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
10420 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
10430 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
10440 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
10450 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
10460 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
10470 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
10480 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
10490 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
104a0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
104b0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
104c0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
104d0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
104e0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
104f0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
10500 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
10510 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
10520 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
10530 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
10540 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
10550 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
10560 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
10570 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
10580 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
10590 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a  _errmsg()]..**.*
105a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
105b0 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 20  .** {F12371} If 
105c0 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  a [sqlite3_get_t
105d0 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20  able()] fails a 
105e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
105f0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
10600 20 20 20 20 69 74 20 66 72 65 65 73 20 74 68 65      it frees the
10610 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e   result table un
10620 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e  der construction
10630 2c 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20  , aborts the.** 
10640 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
10650 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 73  n process, skips
10660 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
10670 71 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 68  queries, sets th
10680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 72  e.**          *r
10690 65 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 6f  esultp output po
106a0 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
106b0 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  d returns [SQLIT
106c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
106d0 7b 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20  {F12373} If the 
106e0 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  ncolumn paramete
106f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
10700 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
10710 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
10720 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
10730 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72  _get_table()] wr
10740 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ite the number o
10750 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
10760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
10770 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
10780 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75  uery into *ncolu
10790 6d 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 20  mn if the query 
107a0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  is.**          s
107b0 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68  uccessful (if th
107c0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
107d0 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a  ns SQLITE_OK)..*
107e0 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 66  *.** {F12374} If
107f0 20 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d 65   the nrow parame
10800 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
10810 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  get_table()] is 
10820 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  not NULL.**     
10830 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
10840 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
10850 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72  write the number
10860 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a   of rows in the.
10870 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
10880 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
10890 65 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69  ery into *nrow i
108a0 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a  f the query is.*
108b0 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
108c0 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75  ssful (if the fu
108d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53  nction returns S
108e0 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a  QLITE_OK)..**.**
108f0 20 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b 73   {F12376} The [s
10900 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10910 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  ()] function set
10920 73 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76  s its *ncolumn v
10930 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
10940 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
10950 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
10960 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
10970 68 65 20 71 75 65 72 79 20 69 6e 20 74 68 65 0a  he query in the.
10980 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 20  **          sql 
10990 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f  parameter, or to
109a0 20 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75 65   zero if the que
109b0 72 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61 6e  ry in sql has an
109c0 20 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20   empty.**       
109d0 20 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a     result set..*
109e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
109f0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
10a00 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
10a10 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
10a20 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
10a30 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
10a40 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
10a50 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
10a60 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20   ***pResult,    
10a70 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
10a80 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
10a90 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20  nt *nrow,       
10aa0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
10ab0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
10ac0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
10ad0 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20  int *ncolumn,   
10ae0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
10af0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
10b00 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
10b10 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
10b20 67 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72  g         /* Err
10b30 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
10b40 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
10b50 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
10b60 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
10b70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10b80 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
10b90 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
10ba0 63 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a  ctions {F17400}.
10bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
10bc0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69  ines are workali
10bd0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
10be0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
10bf0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
10c00 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10c10 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
10c20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
10c30 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
10c40 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
10c50 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
10c60 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
10c70 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
10c80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
10c90 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
10ca0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
10cb0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
10cc0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
10cd0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
10ce0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
10cf0 29 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 69  )].   Both routi
10d00 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
10d10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
10d20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10d30 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
10d40 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
10d50 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
10d60 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
10d70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
10d80 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
10d90 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
10da0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
10db0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
10dc0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
10dd0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
10de0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
10df0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
10e00 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
10e10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
10e20 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
10e30 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
10e40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
10e50 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
10e60 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
10e70 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
10e80 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
10e90 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
10ea0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
10eb0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
10ec0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
10ed0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
10ee0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
10ef0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
10f00 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
10f10 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
10f20 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
10f30 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
10f40 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
10f50 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
10f60 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
10f70 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
10f80 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
10f90 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
10fa0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
10fb0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
10fc0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
10fd0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
10fe0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
10ff0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
11000 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
11010 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
11020 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
11030 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
11040 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
11050 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
11060 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
11070 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
11080 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
11090 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
110a0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
110b0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
110c0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
110d0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
110e0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
110f0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
11100 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
11110 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
11120 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
11130 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
11140 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
11150 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
11160 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
11170 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
11180 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
11190 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
111a0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
111b0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
111c0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
111d0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
111e0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
111f0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
11200 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
11210 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
11220 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
11230 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
11240 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
11250 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
11260 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
11270 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
11280 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
11290 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
112a0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
112b0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
112c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
112d0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
112e0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
112f0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
11300 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
11310 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
11320 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
11330 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
11340 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
11350 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
11360 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
11370 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
11380 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
11390 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
113a0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
113b0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
113c0 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
113d0 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
113e0 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
113f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
11400 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11410 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
11420 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
11430 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
11440 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
11450 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
11460 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
11470 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
11480 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
11490 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
114a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
114b0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
114c0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
114d0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
114e0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
114f0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
11500 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
11510 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
11520 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
11530 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
11540 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
11550 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
11560 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
11570 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
11580 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
11590 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
115a0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
115b0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
115c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
115d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
115e0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
115f0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
11600 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
11610 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11620 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
11630 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
11640 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
11650 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
11660 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
11670 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
11680 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
11690 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
116a0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
116b0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
116c0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
116d0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
116e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
116f0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
11700 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
11710 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
11720 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
11730 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
11740 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
11750 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
11760 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
11770 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
11780 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
11790 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
117a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
117b0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
117c0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
117d0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
117e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
117f0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20  tal string.  Or 
11800 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
11810 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
11820 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55  .** list is a NU
11830 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
11840 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
11850 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
11860 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75  out single.** qu
11870 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
11880 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
11890 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20   {END}  So, for 
118a0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
118b0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
118c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
118d0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
118e0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
118f0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
11900 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
11910 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
11920 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
11930 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
11940 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
11950 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
11960 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
11970 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
11980 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
11990 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
119a0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
119b0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
119c0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
119d0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
119e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
119f0 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  * The "%z" forma
11a00 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
11a10 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
11a20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a  "%s" with the.**
11a30 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
11a40 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
11a50 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
11a60 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
11a70 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
11a80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
11a90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
11aa0 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e  nput string. {EN
11ab0 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  D}.**.** INVARIA
11ac0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  NTS:.**.** {F174
11ad0 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
11ae0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64  3_mprintf()] and
11af0 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   [sqlite3_vmprin
11b00 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  tf()] interfaces
11b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
11b20 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e  turn either poin
11b30 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
11b40 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
11b50 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a  rings held in.**
11b60 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72             memor
11b70 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11b80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11b90 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  )] or NULL point
11ba0 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ers if.**       
11bb0 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73      a call to [s
11bc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11bd0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   fails..**.** {F
11be0 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c  17406}  The [sql
11bf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
11c00 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
11c10 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
11c20 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
11c30 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
11c40 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f  to the buffer po
11c50 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
11c60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
11c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72  .**           pr
11c80 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20  ovided that the 
11c90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11ca0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
11cb0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  zero..**.** {F17
11cc0 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  407}  The [sqlit
11cd0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
11ce0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
11cf0 74 20 77 72 69 74 65 73 20 73 6c 6f 74 73 20 6f  t writes slots o
11d00 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  f.**           i
11d10 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ts output buffer
11d20 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72   (the second par
11d30 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20  ameter) outside 
11d40 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20  the range.**    
11d50 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f         of 0 thro
11d60 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e  ugh N-1 (where N
11d70 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
11d80 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20  rameter).**     
11d90 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73        regardless
11da0 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f   of the length o
11db0 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20  f the string.** 
11dc0 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73            reques
11dd0 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61  ted by the forma
11de0 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e  t specification.
11df0 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a  .**   .*/.char *
11e00 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
11e10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
11e20 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
11e30 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
11e40 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
11e50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
11e60 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
11e70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
11e80 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
11e90 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
11ea0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
11eb0 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17300}.**.** 
11ec0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
11ed0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
11ee0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
11ef0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
11f00 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
11f10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11f20 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
11f30 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
11f40 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
11f50 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
11f60 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
11f70 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
11f80 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
11f90 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
11fa0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
11fb0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
11fc0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
11fd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11fe0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
11ff0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12000 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
12010 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
12020 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
12030 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
12040 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
12050 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
12060 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
12070 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
12080 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
12090 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
120a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
120b0 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  .  If the parame
120c0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
120d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
120e0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
120f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
12100 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
12110 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
12120 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
12130 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
12140 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
12150 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
12160 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
12170 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
12180 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
12190 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
121a0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
121b0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
121c0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  .  The sqlite3_f
121d0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
121e0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
121f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
12200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
12210 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
12220 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
12230 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
12240 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
12250 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
12260 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
12270 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
12280 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
12290 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
122a0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
122b0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
122c0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
122d0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
122e0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
122f0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
12300 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
12310 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
12320 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
12330 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
12340 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
12350 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
12360 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
12370 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
12380 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
12390 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
123a0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66  c() or sqlite3_f
123b0 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ree()..**.** The
123c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
123d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
123e0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
123f0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
12400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12410 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
12420 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
12430 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
12440 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
12450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12460 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
12470 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
12480 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
12490 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
124a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
124b0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
124c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
124d0 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
124e0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
124f0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
12500 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
12510 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
12520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
12530 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
12540 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
12550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
12560 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
12570 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
12580 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
12590 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
125a0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
125b0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
125c0 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
125d0 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
125e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
125f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
12600 2a 2a 20 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** Sqlite3_reall
12610 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
12620 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
12630 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12640 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
12650 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
12660 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
12670 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
12680 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
12690 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
126a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
126b0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
126c0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
126d0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
126e0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
126f0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
12700 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
12710 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
12720 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
12730 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
12740 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
12750 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
12760 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
12770 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
12780 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12790 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
127a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
127b0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
127c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
127d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
127e0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
127f0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
12800 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
12810 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
12820 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
12830 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
12840 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d  on.** of the mem
12850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12860 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68  ubsystem uses th
12870 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
12880 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65  loc().** and fre
12890 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20  e() provided by 
128a0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
128b0 69 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d  ibrary. {F17382}
128c0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a   However, if .**
128d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
128e0 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c  led with the fol
128f0 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63  lowing C preproc
12900 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a  essor macro.**.*
12910 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53  * <blockquote> S
12920 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a  QLITE_MEMORY_SIZ
12930 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62  E=<i>NNN</i> </b
12940 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12950 20 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69   where <i>NNN</i
12960 3e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  > is an integer,
12970 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65   then SQLite cre
12980 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
12990 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
129a0 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74  t <i>NNN</i> byt
129b0 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75  es in size and u
129c0 73 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a  se that array.**
129d0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
129e0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
129f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
12a00 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e   {END}  Addition
12a10 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  al.** memory all
12a20 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d  ocator options m
12a30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
12a40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
12a50 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
12a60 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
12a70 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
12a80 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
12a90 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
12aa0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
12ab0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
12ac0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
12ad0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
12ae0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
12af0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
12b00 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
12b10 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
12b20 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
12b30 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
12b40 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
12b50 61 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20  ators can be.** 
12b60 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
12b70 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
12b80 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
12b90 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
12ba0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
12bb0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
12bc0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
12bd0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
12be0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
12bf0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
12c00 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
12c10 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
12c20 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
12c30 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
12c40 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
12c50 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
12c60 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
12c70 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
12c80 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
12c90 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
12ca0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
12cb0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
12cc0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
12cd0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
12ce0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  M]..**.** INVARI
12cf0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
12d00 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  303}  The [sqlit
12d10 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e  e3_malloc(N)] in
12d20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
12d30 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72  either a pointer
12d40 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
12d50 20 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d    newly checked-
12d60 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20  out block of at 
12d70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66  least N bytes of
12d80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
12d90 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
12da0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a  yte aligned, .**
12db0 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 74             or it
12dc0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
12dd0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
12de0 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71   fulfill the req
12df0 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  uest..**.** {F17
12e00 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  304}  The [sqlit
12e10 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e  e3_malloc(N)] in
12e20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
12e30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
12e40 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e  f.**           N
12e50 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
12e60 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a   equal to zero..
12e70 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20  **.** {F17305}  
12e80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  The [sqlite3_fre
12e90 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(P)] interface 
12ea0 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20  releases memory 
12eb0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
12ec0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64          returned
12ed0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
12ee0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
12ef0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
12f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61  .**           ma
12f10 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c  king it availabl
12f20 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a  e for reuse..**.
12f30 2a 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63  ** {F17306}  A c
12f40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
12f50 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61  free(NULL)] is a
12f60 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
12f70 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20  .**.** {F17310} 
12f80 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
12f90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29  te3_realloc(0,N)
12fa0 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  ] is equivalent 
12fb0 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  to a call.**    
12fc0 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74         to [sqlit
12fd0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a  e3_malloc(N)]..*
12fe0 2a 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41  *.** {F17312}  A
12ff0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
13000 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20  3_realloc(P,0)] 
13010 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
13020 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20   a call.**      
13030 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33       to [sqlite3
13040 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a  _free(P)]..**.**
13050 20 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20 53   {F17315}  The S
13060 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
13070 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13080 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  )], [sqlite3_rea
13090 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
130a0 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74        and [sqlit
130b0 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61  e3_free()] for a
130c0 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79  ll of its memory
130d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a   allocation and.
130e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61  **           dea
130f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
13100 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20  .**.** {F17318} 
13110 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
13120 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65  alloc(P,N)] inte
13130 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
13140 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ther a pointer.*
13150 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61  *           to a
13160 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65   block of checke
13170 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20  d-out memory of 
13180 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
13190 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20   in size.**     
131a0 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d        that is 8-
131b0 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72  byte aligned, or
131c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
131d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20  .**.** {F17321} 
131e0 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   When [sqlite3_r
131f0 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74  ealloc(P,N)] ret
13200 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  urns a non-NULL 
13210 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73  pointer, it firs
13220 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  t.**           c
13230 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20  opies the first 
13240 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65  K bytes of conte
13250 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74  nt from P into t
13260 68 65 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74  he newly allocat
13270 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
13280 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c  where K is the l
13290 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74  esser of N and t
132a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
132b0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
132c0 46 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  F17322}  When [s
132d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
132e0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
132f0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
13300 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
13310 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
13320 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
13330 0a 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68  .** {F17323}  Wh
13340 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
13350 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
13360 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
13370 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
13380 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
13390 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
133a0 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
133b0 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d  :.**.** {U17350}
133c0 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
133d0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
133e0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
133f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13400 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
13410 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13420 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20 70  NULL or else a p
13430 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 20  ointer obtained 
13440 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
13450 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
13460 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
13470 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
13480 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13490 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 20 20  ] that has.**   
134a0 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
134b0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
134c0 20 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61   {U17351}  The a
134d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
134e0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
134f0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a  e any part of .*
13500 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c  *           a bl
13510 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
13520 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
13530 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
13540 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
13550 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
13560 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13570 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  ()]..**.*/.void 
13580 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
13590 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
135a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
135b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
135c0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
135d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
135e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
135f0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
13600 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F17370}.**.** S
13610 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
13620 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
13630 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
13640 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
13650 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
13660 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
13670 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
13680 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
13690 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d  lloc()].** the m
136a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
136b0 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75   subsystem inclu
136c0 64 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 53  ded within the S
136d0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  QLite..**.** INV
136e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
136f0 46 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c  F17371} The [sql
13700 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
13710 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
13720 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
13730 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
13740 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  tes of memory cu
13750 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
13760 69 6e 67 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ing .**         
13770 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
13780 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a  ot freed)..**.**
13790 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73   {F17373} The [s
137a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
137b0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
137c0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
137d0 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20  aximum.**       
137e0 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c     value of [sql
137f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
13800 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()] .**         
13810 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
13820 77 61 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c  water mark was l
13830 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a  ast reset..**.**
13840 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76 61   {F17374} The va
13850 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
13860 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13870 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
13880 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
13890 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
138a0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
138b0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20  y overhead.**   
138c0 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20         added by 
138d0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
138e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
138f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13900 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
13910 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
13920 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
13930 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
13940 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20  tem library.**  
13950 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73          routines
13960 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
13970 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
13980 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37  l..** .** {F1737
13990 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  5} The memory hi
139a0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
139b0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
139c0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
139d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
139e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
139f0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
13a00 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
13a10 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
13a20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13a30 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
13a40 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20  rue.  The value 
13a50 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
13a60 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
13a70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13a80 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
13a90 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
13aa0 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74           prior t
13ab0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
13ac0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
13ad0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13ae0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
13af0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
13b00 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
13b10 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
13b20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13b30 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
13b40 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
13b50 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F17390}.**.** S
13b60 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
13b70 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
13b80 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
13b90 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
13ba0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
13bb0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
13bc0 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
13bd0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
13be0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
13bf0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
13c00 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
13c10 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
13c20 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
13c30 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
13c40 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
13c50 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
13c60 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
13c70 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
13c80 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
13c90 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
13ca0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
13cb0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
13cc0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
13cd0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
13ce0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
13cf0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
13d00 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
13d10 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
13d20 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
13d30 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
13d40 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
13d50 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
13d60 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
13d70 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
13d80 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
13d90 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
13da0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
13db0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
13dc0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
13dd0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
13de0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
13df0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
13e00 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
13e10 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
13e20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
13e30 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
13e40 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13e50 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
13e60 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
13e70 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
13e80 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65  .** {F17392} The
13e90 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
13ea0 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
13eb0 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
13ec0 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
13ed0 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
13ee0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
13ef0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
13f00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
13f10 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
13f20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
13f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13f40 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
13f50 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
13f60 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a  ks {F12500}.**.*
13f70 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
13f80 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
13f90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
13fa0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
13fb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13fc0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
13fd0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
13fe0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
13ff0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14000 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14010 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
14020 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
14030 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
14040 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
14050 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
14060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14070 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
14080 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
14090 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
140a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
140b0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
140c0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
140d0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
140e0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
140f0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
14100 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
14110 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
14120 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14130 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14140 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
14150 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
14160 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
14170 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14180 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
14190 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
141a0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
141b0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
141c0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
141d0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
141e0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
141f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14200 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
14210 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
14220 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
14230 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
14240 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
14250 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
14260 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
14270 72 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20 61  rror.   If the a
14280 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14290 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
142a0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
142b0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
142c0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
142d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
142e0 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ].** then [sqlit
142f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14300 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
14310 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
14320 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
14330 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
14340 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
14350 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
14360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
14370 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
14380 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
14390 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
143a0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
143b0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
143c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
143d0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
143e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
143f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
14400 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
14410 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
14420 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
14430 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
14440 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
14450 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
14460 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
14470 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
14480 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
14490 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
144a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
144b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
144c0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
144d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
144e0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
144f0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
14500 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
14510 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
14520 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
14530 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
14540 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
14550 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
14560 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
14570 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
14580 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
14590 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
145a0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
145b0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
145c0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
145d0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
145e0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  f a table..**.**
145f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
14600 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
14610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
14620 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
14630 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
14640 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
14650 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14660 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
14670 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
14680 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
14690 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
146a0 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  eger .** [SQLITE
146b0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
146c0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
146d0 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
146e0 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  ar action.** to 
146f0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54  be authorized. T
14700 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
14710 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65   sixth.** parame
14720 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
14730 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
14740 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
14750 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a   that contain .*
14760 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  * additional det
14770 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
14780 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
14790 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
147a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
147b0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
147c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
147d0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
147e0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
147f0 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f   untrusted.** so
14800 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
14810 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
14820 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74  tements do not t
14830 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
14840 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61  a.** that they a
14850 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
14860 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
14870 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  hey do not try t
14880 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c  o.** execute mal
14890 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
148a0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
148b0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
148c0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
148d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
148e0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
148f0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
14900 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
14910 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
14920 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
14930 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
14940 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
14950 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
14960 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
14970 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
14980 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
14990 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
149a0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
149b0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
149c0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
149d0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
149e0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
149f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
14a00 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
14a10 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
14a20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
14a30 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
14a40 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
14a50 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
14a60 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
14a70 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
14a80 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
14a90 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
14aa0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
14ab0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
14ac0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
14ad0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
14ae0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
14af0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
14b00 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
14b10 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
14b20 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
14b30 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
14b40 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
14b50 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
14b60 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
14b70 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
14b80 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
14b90 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
14ba0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
14bb0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
14bc0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
14bd0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
14be0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
14bf0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
14c00 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
14c10 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
14c20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
14c30 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
14c40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14c50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
14c60 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
14c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
14c80 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
14c90 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
14ca0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
14cb0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
14cc0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
14cd0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
14ce0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  tep()]..**.** IN
14cf0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14d00 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71  {F12501} The [sq
14d10 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
14d20 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  izer(D,...)] int
14d30 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
14d40 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
14d50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14d60 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ck with database
14d70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
14d80 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54 68  *.** {F12502} Th
14d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14da0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14db0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
14dc0 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ts are.**       
14dd0 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65     being compile
14de0 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d  d.**.** {F12503}
14df0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
14e00 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
14e10 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  rns any value ot
14e20 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
14e30 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
14e40 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
14e50 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
14e60 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  NY] then.**     
14e70 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
14e80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
14e90 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
14ea0 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ll that caused.*
14eb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
14ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14ed0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
14ee0 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20  fail with an.** 
14ef0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
14f00 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
14f10 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  de and an approp
14f20 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
14f30 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  age..**.** {F125
14f40 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  04} When the aut
14f50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14f60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
14f70 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74  _OK], the operat
14f80 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
14f90 64 65 73 63 72 69 62 65 64 20 69 73 20 63 6f 64  described is cod
14fa0 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
14fb0 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 65 6e  ** {F12505} When
14fc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14fd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
14fe0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
14ff0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15000 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15010 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
15020 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
15030 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
15040 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
15050 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
15060 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
15070 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
15080 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
15090 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
150a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
150b0 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
150c0 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
150d0 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
150e0 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 20 74  ** {F12506} If t
150f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
15100 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
15110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
15120 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
15130 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
15140 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
15150 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
15160 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
15170 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
15180 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
15190 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
151a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
151b0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
151c0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
151d0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
151e0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
151f0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
15200 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
15210 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
15220 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
15230 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
15240 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 37 7d  ..**.** {F12507}
15250 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
15260 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
15270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
15280 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
15290 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
152a0 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
152b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
152c0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
152d0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
152e0 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
152f0 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
15300 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
15310 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a  LITE_DENY]. .**.
15320 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65 20  ** {F12510} The 
15330 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15340 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
15350 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
15360 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
15370 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
15380 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
15390 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
153a0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
153b0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ace..**.** {F125
153c0 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
153d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
153e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
153f0 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20 20 20  nteger .**      
15400 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
15410 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
15420 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15430 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
15440 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
15450 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
15460 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 32  d..**.** {F12512
15470 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
15480 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
15490 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
154a0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
154b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
154c0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
154d0 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20 20  t contain .**   
154e0 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61         additiona
154f0 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
15500 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
15510 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
15520 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68  ** {F12520} Each
15530 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
15540 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15550 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  ()] overrides th
15560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  e.**          an
15570 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
15580 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
15590 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31  r..**.** {F12521
155a0 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
155b0 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
155c0 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
155d0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
155e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
155f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20  .**.** {F12522} 
15600 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
15610 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
15620 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
15630 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
15640 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
15650 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
15660 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
15670 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
15680 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
15690 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
156a0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
156b0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
156c0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
156d0 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a  des {F12590}.**.
156e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
156f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
15700 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15710 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
15720 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
15730 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
15740 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
15750 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
15760 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
15770 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
15780 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
15790 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
157a0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
157b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
157c0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
157d0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
157e0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
157f0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
15800 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
15810 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
15820 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
15830 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
15840 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
15850 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
15860 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
15870 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
15880 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
15890 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
158a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
158b0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
158c0 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a  odes {F12550}.**
158d0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
158e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
158f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
15900 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
15910 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
15920 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
15930 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74   authorizer cert
15940 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
15950 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
15960 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
15970 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
15980 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
15990 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
159a0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
159b0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
159c0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
159d0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
159e0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
159f0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
15a00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
15a10 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
15a20 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
15a30 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
15a40 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
15a50 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
15a60 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   be .** authoriz
15a70 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
15a80 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
15a90 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
15aa0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
15ab0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
15ac0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
15ad0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
15ae0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
15af0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
15b00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15b10 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
15b20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
15b30 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
15b40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
15b50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
15b60 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
15b70 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63   "temp", .** etc
15b80 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
15b90 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
15ba0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
15bb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
15bc0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
15bd0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
15be0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
15bf0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
15c00 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
15c10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
15c20 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
15c30 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
15c40 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a   directly from .
15c50 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
15c60 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   code..**.** INV
15c70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
15c80 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f  F12551} The seco
15c90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
15ca0 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  an .**          
15cb0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
15cc0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
15cd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
15ce0 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65  s always an inte
15cf0 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
15d00 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
15d10 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
15d20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77  that specifies w
15d30 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  hat action.**   
15d40 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20         is being 
15d50 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
15d60 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33  * {F12552} The 3
15d70 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
15d80 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a 2a  eters to the .**
15d90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15da0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
15db0 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
15dc0 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  n callback funct
15dd0 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion].**         
15de0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
15df0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
15e00 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 0a  nding on which .
15e10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
15e20 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
15e30 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75  rizer code] is u
15e40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15e50 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
15e60 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20  ** {F12553} The 
15e70 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
15e80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15e90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
15ea0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
15eb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
15ec0 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
15ed0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64          of the d
15ee0 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65  atabase (example
15ef0 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  : "main", "temp"
15f00 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  , etc.) if appli
15f10 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cable..**.** {F1
15f20 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61  2554} The 6th pa
15f30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
15f40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
15f50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
15f60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
15f70 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
15f80 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
15f90 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d    of the inner-m
15fa0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
15fb0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
15fc0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20  onsible for.**  
15fd0 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65          the acce
15fe0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
15ff0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
16000 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
16010 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 20  ectly from .**  
16020 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
16030 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
16040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
16070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
16080 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
16090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
160a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
160b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
160c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
160d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
160e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
160f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
16100 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
16110 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16120 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16130 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
16140 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
16150 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
16160 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
16170 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
16180 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
16190 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
161a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
161b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
161c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
161d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
161e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
161f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
16200 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
16210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16220 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
16230 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
16240 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
16250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
16260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16270 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
16280 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
16290 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
162a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
162b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
162c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
162d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
162e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
162f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16310 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
16320 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
16330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
16340 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
16350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16360 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
16370 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
16380 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
16390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
163a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
163b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
163c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
163d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
163e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
163f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16400 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
16410 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
16420 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
16430 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16450 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
16460 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
16470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
16480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
164a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
164b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
164c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
164d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
164e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
164f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
16500 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
16510 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
16520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16540 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
16550 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
16560 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
16570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
16590 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
165a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
165b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
165c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
165d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
165e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
165f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
16600 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16610 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16620 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
16630 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
16640 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
16650 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
16660 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
16670 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
16680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16690 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
166a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
166b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
166c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
166d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
166e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
166f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16710 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
16720 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
16730 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
16740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
16750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16760 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
16770 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
16780 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
16790 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
167a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
167b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
167c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
167d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
167e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
167f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16800 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
16810 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
16820 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
16830 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
16840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16850 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
16860 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
16870 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
16880 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
168a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
168b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
168c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
168d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
168e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
168f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
16900 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
16910 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
16920 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16940 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
16950 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
16960 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
16970 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
16980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16990 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
169a0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
169b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
169c0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
169d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
169e0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
169f0 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63      31   /* Func
16a00 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  tion Name   NULL
16a10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16a30 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
16a40 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
16a50 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
16a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
16a70 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
16a80 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  ing Functions {F
16a90 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12280}.**.** The
16aa0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
16ab0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
16ac0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
16ad0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
16ae0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
16af0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
16b00 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
16b10 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
16b20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16b30 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
16b40 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
16b50 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
16b60 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
16b70 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
16b80 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
16b90 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
16ba0 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
16bb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16bc0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
16bd0 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
16be0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
16bf0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
16c00 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
16c10 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
16c20 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
16c30 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
16c40 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
16c50 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
16c60 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
16c70 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
16c80 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
16c90 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
16ca0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
16cb0 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54  rigger..** .** T
16cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
16cd0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
16ce0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
16cf0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
16d00 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
16d10 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
16d20 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
16d30 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
16d40 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
16d50 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
16d60 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
16d70 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
16d80 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
16d90 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
16da0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
16db0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16dc0 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
16dd0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
16de0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
16df0 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
16e00 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
16e10 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20  or removal in a 
16e20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a  future release..
16e30 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65  **.** The trigge
16e40 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74  r reporting feat
16e50 75 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65  ure of the trace
16e60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e   callback is con
16e70 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72  sidered.** exper
16e80 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
16e90 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
16ea0 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66   or removal in f
16eb0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
16ec0 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  ** Future versio
16ed0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
16ee0 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20  ht also add new 
16ef0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a  trace callback .
16f00 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a  ** invocations..
16f10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16f20 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d  :.**.** {F12281}
16f30 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
16f40 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
16f50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  d by [sqlite3_tr
16f60 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20  ace()] is.**    
16f70 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
16f80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
16f90 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
16fa0 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20  execute and.**  
16fb0 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
16fc0 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
16fd0 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69  ogram first begi
16fe0 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ns to run..**.**
16ff0 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20 63   {F12282} Each c
17000 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
17010 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64  trace()] overrid
17020 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c  es the previousl
17030 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
17040 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63  gistered trace c
17050 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
17060 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74  F12283} A NULL t
17070 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69  race callback di
17080 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a  sables tracing..
17090 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54  **.** {F12284} T
170a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
170b0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
170c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
170d0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
170e0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69   the pointer whi
170f0 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61  ch was the 3rd a
17100 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
17110 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a  te3_trace()]..**
17120 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65  .** {F12285} The
17130 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17140 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
17150 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
17160 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
17170 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
17180 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
17190 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
171a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
171b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
171c0 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
171d0 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
171e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
171f0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
17200 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
17210 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
17220 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
17230 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
17240 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
17250 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
17260 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65  .** {F12287} The
17270 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17280 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
17290 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
172a0 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
172b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
172c0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
172d0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
172e0 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66  * {F12288} The f
172f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17300 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
17310 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
17320 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
17330 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
17340 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
17350 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
17360 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {F12289} The sec
17370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17380 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
17390 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
173a0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
173b0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
173c0 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
173d0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
173e0 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
173f0 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
17400 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
17410 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
17420 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17430 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
17440 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
17450 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d  ..**.** {F12290}
17460 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
17470 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
17480 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20 69 73  ile  callback is
17490 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20   an estimate.** 
174a0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
174b0 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
174c0 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c  conds of wall-cl
174d0 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65  ock time require
174e0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
174f0 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61   run the SQL sta
17500 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72  tement from star
17510 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a  t to finish..*/.
17520 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
17530 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
17540 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
17550 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
17560 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
17570 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
17580 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
17590 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
175a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
175b0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
175c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
175d0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
175e0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
175f0 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12910}.**.** T
17600 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
17610 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
17620 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
17630 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
17640 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
17650 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
17660 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
17670 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
17680 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
17690 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
176a0 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
176b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
176c0 65 28 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70  e()].   An examp
176d0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20  le use for this 
176e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
176f0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
17700 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
17710 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
17720 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
17730 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
17740 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
17750 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
17760 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
17770 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
17780 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
17790 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
177a0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
177b0 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  GUI dialog box..
177c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
177d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d  :.**.** {F12911}
177e0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
177f0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
17800 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
17810 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
17820 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
17830 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
17840 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
17850 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
17860 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
17870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17880 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20  .**.** {F12912} 
17890 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
178a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
178b0 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
178c0 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20  N virtual.**    
178d0 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70        machine op
178e0 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
178f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
17900 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20  ument to .**    
17910 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
17920 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
17930 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  ler()] call that
17940 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
17950 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
17960 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61  back.  <todo>Wha
17970 74 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  t if N is less t
17980 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  han 1?</todo>.**
17990 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65  .** {F12913} The
179a0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
179b0 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65  ck itself is ide
179c0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74  ntified by the t
179d0 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hird.**         
179e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
179f0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17a00 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  andler()]..**.**
17a10 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f   {F12914} The fo
17a20 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 5b 73  urth argument [s
17a30 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
17a40 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 20 61 0a  handler()] is a.
17a50 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64  ***         void
17a60 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
17a70 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
17a80 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
17a90 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
17aa0 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
17ab0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
17ac0 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
17ad0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
17ae0 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
17af0 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ewer than.**    
17b00 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20        N opcodes 
17b10 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a  being executed,.
17b20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
17b30 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
17b40 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
17b50 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a  invoked. {END}.*
17b60 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45  * .** {F12916} E
17b70 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71  very call to [sq
17b80 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17b90 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20  andler()].**    
17ba0 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73        overwrites
17bb0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
17bc0 72 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72  registered progr
17bd0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  ess handler..**.
17be0 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20 74  ** {F12917} If t
17bf0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
17c00 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
17c10 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f  NULL then no pro
17c20 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20  gress.**        
17c30 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76    handler is inv
17c40 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
17c50 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67  918} If the prog
17c60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
17c70 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f  turns a result o
17c80 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65  ther than 0, the
17c90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
17ca0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20  e behavior is a 
17cb0 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  if [sqlite3_inte
17cc0 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65  rrupt()] had bee
17cd0 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69  n called..*/.voi
17ce0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
17cf0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
17d00 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
17d10 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
17d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17d30 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
17d40 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17d50 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a  ion {F12700}.**.
17d60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17d70 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
17d80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
17d90 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20  hose name.** is 
17da0 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69 6c  given by the fil
17db0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ename argument..
17dc0 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  ** The filename 
17dd0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
17de0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
17df0 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  .** for [sqlite3
17e00 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
17e10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17e20 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
17e30 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
17e40 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
17e50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
17e60 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  ]..** An [sqlite
17e70 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  3*] handle is us
17e80 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 20 69  ually returned i
17e90 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a  n *ppDb, even.**
17ea0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
17eb0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
17ec0 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 20 53  xception is if S
17ed0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 0a  QLite is unable.
17ee0 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ** to allocate m
17ef0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
17f00 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
17f10 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a  ct, a NULL will.
17f20 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ** be written in
17f30 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
17f40 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
17f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
17f60 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65  bject..** If the
17f70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
17f80 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
17f90 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 73 66  ted).** successf
17fa0 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49  ully, then [SQLI
17fb0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
17fc0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
17fd0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
17fe0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
17ff0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
18000 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
18010 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
18020 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
18030 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
18040 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
18050 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
18060 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
18070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
18080 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
18090 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
180a0 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
180b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
180c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
180d0 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
180e0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
180f0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
18100 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71  yte order if [sq
18110 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
18120 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
18130 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
18140 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
18150 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
18160 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
18170 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
18180 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  e [sqlite3*] han
18190 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
181a0 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e  leased by passin
181b0 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  g it.** to [sqli
181c0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
181d0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
181e0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
181f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  * The [sqlite3_o
18200 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
18210 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b  ace works like [
18220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
18230 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
18240 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
18250 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
18260 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
18270 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
18280 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
18290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
182a0 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61    The flags para
182b0 6d 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20  meter can be.** 
182c0 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  one of:.**.** <o
182d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
182e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
182f0 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  Y].** <li>  [SQL
18300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
18310 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  TE].** <li>  [SQ
18320 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
18330 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
18340 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c  PEN_CREATE].** <
18350 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ol>.**.** The f
18360 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73  irst value opens
18370 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65   the database re
18380 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20  ad-only. .** If 
18390 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
183a0 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  s not previously
183b0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
183c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
183d0 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69   The second opti
183e0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20  on opens.** the 
183f0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
18400 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
18410 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
18420 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
18430 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20  .** if the file 
18440 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
18450 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63  ed.  In either c
18460 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
18470 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64 79  .** must already
18480 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72   exist or an err
18490 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  or is returned. 
184a0 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f   The third optio
184b0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20 64  n.** opens the d
184c0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
184d0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
184e0 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20 69  and creates it i
184f0 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
18500 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a   already exist..
18510 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74  ** The third opt
18520 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72  ions is behavior
18530 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
18540 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65  used for [sqlite
18550 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  3_open()].** and
18560 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
18570 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
18580 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
18590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
185a0 5f 76 32 28 29 5d 20 69 73 20 6e 6f 74 20 6f 6e  _v2()] is not on
185b0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
185c0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
185d0 62 6f 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  bove then the be
185e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
185f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
18600 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
18610 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
18620 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d  n private.** in-
18630 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
18640 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
18650 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
18660 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a  This in-memory.*
18670 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  * database will 
18680 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20  vanish when the 
18690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
186a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
186b0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
186c0 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  n of SQLite migh
186d0 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  t make use of ad
186e0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
186f0 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68   filenames.** th
18700 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
18710 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
18720 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e    It is recommen
18730 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65  ded that .** whe
18740 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
18750 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65  ename really doe
18760 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
18770 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65  ":" that you pre
18780 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
18790 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
187a0 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a   like "./" to.**
187b0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
187c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
187d0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
187e0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
187f0 20 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f   a private tempo
18800 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
18810 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
18820 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
18830 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
18840 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
18850 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
18860 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
18870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18880 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
18890 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
188a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
188b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
188c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
188d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
188e0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
188f0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
18900 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a  ating system .**
18910 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
18920 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
18930 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
18940 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a  ld use.  If the.
18950 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
18960 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ter is a NULL po
18970 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
18980 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
18990 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  vfs].** object i
189a0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
189b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
189c0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
189d0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
189e0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
189f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b  argument.** of [
18a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
18a10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
18a20 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20  n_v2()] must be 
18a30 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
18a40 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
18a50 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
18a60 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
18a70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
18a80 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
18a90 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
18aa0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
18ab0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
18ac0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
18ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
18ae0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
18af0 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  en_v2()]..**.** 
18b00 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18b10 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20 5b  * {F12701} The [
18b20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
18b30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
18b40 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
18b50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
18b60 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
18b70 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77  ces create a new
18b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
18b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18ba0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
18bb0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
18bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18bd0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20   given in their 
18be0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
18bf0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20  .**.** {F12702} 
18c00 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
18c10 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
18c20 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
18c30 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73            for [s
18c40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
18c50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
18c60 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
18c70 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
18c80 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
18c90 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
18ca0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
18cb0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d  ..**.** {F12703}
18cc0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
18cd0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
18ce0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
18cf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
18d00 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  , .**          o
18d10 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
18d20 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70  v2()] writes a p
18d30 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
18d40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
18d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18d60 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a  ] into *ppDb..**
18d70 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65  .** {F12704} The
18d80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
18d90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
18da0 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
18db0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18dc0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
18dd0 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51  faces return [SQ
18de0 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75  LITE_OK] upon su
18df0 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ccess,.**       
18e00 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72     or an appropr
18e10 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
18e20 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
18e30 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65  .** {F12706} The
18e40 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
18e50 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
18e60 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
18e70 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
18e80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
18e90 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
18ea0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c  _open_v2()] will
18eb0 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   be UTF-8..**.**
18ec0 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65   {F12707} The de
18ed0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
18ee0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
18ef0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
18f00 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
18f10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
18f20 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
18f30 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  16..**.** {F1270
18f40 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
18f50 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72  open(F,D)] inter
18f60 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
18f70 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
18f80 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
18f90 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65  v2(F,D,G,0)] whe
18fa0 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  re the G paramet
18fb0 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
18fc0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
18fd0 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54  EADWRITE]|[SQLIT
18fe0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a  E_OPEN_CREATE]..
18ff0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49  **.** {F12711} I
19000 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
19010 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
19020 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
19030 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
19040 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
19050 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
19060 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74  READONLY] then t
19070 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19080 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
19090 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e    for reading on
190a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ly..**.** {F1271
190b0 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  2} If the G para
190c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
190d0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
190e0 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
190f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
19100 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
19110 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74  PEN_READWRITE] t
19120 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
19130 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
19140 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61         reading a
19150 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
19160 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72  ssible, or for r
19170 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74  eading only if t
19180 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
19190 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
191a0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
191b0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a  erating system..
191c0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49  **.** {F12713} I
191d0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
191e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
191f0 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
19200 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  omits the.**    
19210 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
19220 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
19230 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
19240 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
19250 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
19260 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
19270 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
19280 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34  d..**.** {F12714
19290 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
192a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
192b0 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
192c0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
192d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
192e0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
192f0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
19300 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
19310 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
19320 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
19330 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d  t, then an attem
19340 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72  pt is made to cr
19350 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eate and.**     
19360 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20       initialize 
19370 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  the database..**
19380 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20  .** {F12717} If 
19390 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
193a0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
193b0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
193c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
193d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
193e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
193f0 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  ] is ":memory:",
19400 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65   then an private
19410 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
19420 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f  hemeral, in-memo
19430 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
19440 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
19450 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20  onnection..**   
19460 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
19470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
19480 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
19490 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
194a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
194b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
194c0 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
194d0 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65   {F12719} If the
194e0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c   filename is NUL
194f0 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
19500 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
19510 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
19520 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64    ephemeral on-d
19530 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
19540 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
19550 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
19560 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
19570 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
19580 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
19590 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
195a0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
195b0 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
195c0 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
195d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195e0 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
195f0 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  y .**          [
19600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19610 46 2c 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75  F,D,G,V)] will u
19620 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  se the.**       
19630 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d     [sqlite3_vfs]
19640 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69   object identifi
19650 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61  ed by the V para
19660 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20  meter, or.**    
19670 20 20 20 20 20 20 74 68 65 20 64 65 66 61 75 6c        the defaul
19680 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
19690 6f 62 6a 65 63 74 20 69 73 20 56 20 69 73 20 61  object is V is a
196a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
196b0 2a 0a 2a 2a 20 7b 46 31 32 37 32 33 7d 20 54 77  *.** {F12723} Tw
196c0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
196d0 65 63 74 69 6f 6e 20 7c 20 64 61 74 61 62 61 73  ection | databas
196e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
196f0 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d  ill share a comm
19700 6f 6e 20 63 61 63 68 65 0a 2a 2a 20 20 20 20 20  on cache.**     
19710 20 20 20 20 20 69 66 20 62 6f 74 68 20 77 65 72       if both wer
19720 65 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68  e opened with th
19730 65 20 73 61 6d 65 20 56 46 53 0a 2a 2a 20 20 20  e same VFS.**   
19740 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71         while [sq
19750 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
19760 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61 72  red_cache | shar
19770 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 77 61  ed cache mode wa
19780 73 20 65 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 2a  s enabled] and.*
19790 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f  *          if bo
197a0 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d  th filenames com
197b0 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67  pare equal using
197c0 20 6d 65 6d 63 6d 70 28 29 0a 2a 2a 20 20 20 20   memcmp().**    
197d0 20 20 20 20 20 20 61 66 74 65 72 20 68 61 76 69        after havi
197e0 6e 67 20 62 65 65 6e 20 70 72 6f 63 65 73 73 65  ng been processe
197f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
19800 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74  3_vfs | xFullPat
19810 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66  hname] method of
19820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
19830 20 56 46 53 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20   VFS..**.*/.int 
19840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
19850 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
19860 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
19870 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
19880 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
19890 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
198a0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
198b0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
198c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
198d0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
198e0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
198f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
19900 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
19910 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
19920 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
19930 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
19940 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
19950 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
19960 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
19970 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
19980 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
19990 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
199a0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
199b0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
199c0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
199d0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
199e0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
199f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
19a00 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
19a10 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
19a20 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
19a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a40 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
19a50 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38  d Messages {F128
19a60 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
19a70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
19a80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
19a90 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
19aa0 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
19ab0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53  sult code] or [S
19ac0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
19ad0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
19ae0 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20  lt code].** for 
19af0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
19b00 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
19b10 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
19b20 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71  ated.** with [sq
19b30 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64  lite3] handle 'd
19b40 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  b'. If a prior A
19b50 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62  PI call failed b
19b60 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  ut the.** most r
19b70 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
19b80 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
19b90 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
19ba0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
19bb0 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
19bc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
19bd0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
19be0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
19bf0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
19c00 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
19c10 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
19c20 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
19c30 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72  s either UTF8 or
19c40 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76   UTF16 respectiv
19c50 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
19c60 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
19c70 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
19c80 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
19c90 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
19ca0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
19cb0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
19cc0 20 77 69 74 68 20 66 72 65 65 69 6e 67 20 74 68   with freeing th
19cd0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
19ce0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
19cf0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
19d00 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
19d10 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
19d20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
19d30 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
19d40 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
19d50 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
19d60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
19d70 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c  F12801} The [sql
19d80 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d  ite3_errcode(D)]
19d90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19da0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a  ns the numeric.*
19db0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
19dc0 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
19dd0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ode] or.**      
19de0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52      [SQLITE_IOER
19df0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
19e00 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  d result code].*
19e10 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74  *          for t
19e20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
19e30 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
19e40 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
19e50 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
19e60 74 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  th [database con
19e70 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
19e80 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65 20 5b  * {F12803} The [
19e90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44  sqlite3_errmsg(D
19ea0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
19eb0 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20  errmsg16(D)].** 
19ec0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
19ed0 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  ces return Engli
19ee0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
19ef0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a   that describes.
19f00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19f10 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73  error in the mos
19f20 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69  tly recently fai
19f30 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
19f40 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ll,.**          
19f50 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65  encoded as eithe
19f60 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  r UTF8 or UTF16 
19f70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
19f80 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54 68 65  .** {F12807} The
19f90 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
19fa0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
19fb0 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
19fc0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
19fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
19fe0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
19ff0 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1a000 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1a010 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c  ** {F12808} Call
1a020 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1a030 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1a040 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1a050 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1a060 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1a070 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1a080 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1a090 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1a0a0 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1a0b0 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1a0c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a0d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a0e0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1a0f0 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1a100 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1a110 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e  *.** {F12809} In
1a120 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
1a130 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64  e not associated
1a140 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63   with a specific
1a150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1a160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a170 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  n] (examples:.**
1a180 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a190 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72  e3_mprintf()] or
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1a1b0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1a1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20  .**          do 
1a1d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1a1e0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1a1f0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1a200 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1a210 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1a220 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1a230 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1a240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1a250 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1a260 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1a270 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1a280 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1a290 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1a2a0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1a2b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a2c0 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1a2d0 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30  t Object {F13000
1a2e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1a2f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a300 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1a310 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1a320 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1a330 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1a340 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1a350 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
1a360 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  his.** object is
1a370 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1a380 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1a390 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
1a3a0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1a3b0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1a3c0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1a3d0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
1a3e0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
1a3f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
1a400 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
1a410 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1a420 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
1a430 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
1a440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1a450 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
1a460 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
1a470 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
1a480 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
1a490 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
1a4a0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
1a4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1a4c0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
1a4d0 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
1a4e0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1a4f0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1a500 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a510 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1a520 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1a530 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1a540 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1a550 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1a560 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1a570 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1a580 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1a590 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1a5a0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1a5b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1a5c0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1a5d0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1a5e0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1a5f0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1a600 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1a610 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1a620 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1a630 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1a640 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1a650 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1a660 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1a670 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36  me Limits {F1276
1a680 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1a690 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1a6a0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1a6b0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1a6c0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1a6d0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1a6e0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1a6f0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1a700 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1a710 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1a720 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1a730 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1a740 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1a750 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1a760 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1a770 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1a780 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1a790 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1a7a0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1a7b0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1a7c0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1a7d0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1a7e0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1a7f0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1a800 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1a810 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1a820 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1a830 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1a840 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1a850 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1a860 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
1a870 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1a880 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1a890 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1a8a0 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
1a8b0 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
1a8c0 6d 70 69 6c 65 2d 74 69 6d 65 20 43 2d 70 72 65  mpile-time C-pre
1a8d0 70 72 6f 63 65 73 73 20 6d 61 63 72 6f 20 6e 61  process macro na
1a8e0 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  med SQLITE_MAX_X
1a8f0 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  YZ..** (The "_LI
1a900 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1a910 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1a920 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74  "_MAX_".).** Att
1a930 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1a940 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1a950 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1a960 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1a970 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1a980 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1a990 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75   limit..**.** Ru
1a9a0 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n time limits ar
1a9b0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1a9c0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1a9d0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1a9e0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1a9f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1aa00 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1aa10 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1aa20 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1aa30 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1aa40 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1aa50 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1aa60 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1aa70 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61  * webbrowser tha
1aa80 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
1aa90 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
1aaa0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
1aab0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
1aac0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
1aad0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
1aae0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
1aaf0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
1ab00 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
1ab10 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1ab20 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
1ab30 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
1ab40 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
1ab50 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
1ab60 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
1ab70 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
1ab80 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
1ab90 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
1aba0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
1abb0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
1abc0 65 0a 2a 2a 20 61 74 74 61 63 68 2e 20 20 44 65  e.** attach.  De
1abd0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
1abe0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
1abf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
1ac00 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
1ac10 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
1ac20 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
1ac30 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
1ac40 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
1ac50 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
1ac60 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
1ac70 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
1ac80 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
1ac90 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
1aca0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1acb0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  ]..**.** This in
1acc0 74 65 72 66 61 63 65 20 69 73 20 63 75 72 72 65  terface is curre
1acd0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20  ntly considered 
1ace0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1acf0 20 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74   is subject.** t
1ad00 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f  o change or remo
1ad10 76 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69 6f  val without prio
1ad20 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20  r notice..**.** 
1ad30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ad40 2a 20 7b 46 31 32 37 36 32 7d 20 41 20 73 75 63  * {F12762} A suc
1ad50 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1ad60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1ad70 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1ad80 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
1ad90 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
1ada0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  he.**          l
1adb0 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1adc0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1add0 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  in [database con
1ade0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
1adf0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6c 65         to the le
1ae00 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68  sser of V and th
1ae10 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
1ae20 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a  nd on the size.*
1ae30 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 43 20  *          of C 
1ae40 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63  that is set at c
1ae50 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a  ompile-time..**.
1ae60 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73 75  ** {F12766} A su
1ae70 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1ae80 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1ae90 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1aea0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
1aeb0 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74          leaves t
1aec0 68 65 20 73 74 61 74 65 20 6f 66 20 5b 64 61 74  he state of [dat
1aed0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aee0 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ] D unchanged..*
1aef0 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41 20  *.** {F12769} A 
1af00 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1af10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
1af20 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e  t(D,C,V)] return
1af30 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1af40 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c    value of the l
1af50 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1af60 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1af70 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  in.**          i
1af80 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1af90 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20  ection] D as it 
1afa0 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65  was prior to the
1afb0 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   call..*/.int sq
1afc0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
1afd0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
1afe0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
1aff0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1b000 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
1b010 6f 72 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a  ories {F12790}.*
1b020 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1b030 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
1b040 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
1b050 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  ** .** These con
1b060 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1b070 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66  rious aspects of
1b080 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b090 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
1b0a0 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20   can be limited 
1b0b0 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73  in size by calls
1b0c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1b0d0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65  it()]..** The me
1b0e0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
1b0f0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65  rious limits are
1b100 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b110 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
1b120 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1b130 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1b140 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1b150 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72 69 6e 67  of any.** string
1b160 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74 61 62 6c   or blob or tabl
1b170 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a  e row.<dd>.**.**
1b180 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1b190 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1b1a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b1b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1b1c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1b1d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1b1e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1b1f0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1b200 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b210 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1b220 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1b230 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1b240 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1b250 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d   SELECT or the m
1b260 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1b270 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1b280 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1b290 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1b2a0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1b2b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1b2c0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1b2d0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
1b2e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
1b2f0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
1b300 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
1b310 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ession.</dd>.**.
1b320 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1b330 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1b340 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1b350 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b360 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1b370 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1b380 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1b390 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1b3a0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
1b3b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b3c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1b3d0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
1b3e0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
1b3f0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
1b400 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1b410 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1b420 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1b430 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1b440 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1b450 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1b460 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1b470 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1b480 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
1b490 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1b4a0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
1b4b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1b4c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74  mum number of at
1b4d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1b4e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1b4f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1b500 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1b510 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1b520 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1b530 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1b540 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1b550 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20  LIKE or.** GLOB 
1b560 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a  operators.</dd>.
1b570 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1b580 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1b590 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1b5a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b5b0 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1b5c0 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1b5d0 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1b5e0 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1b5f0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1b600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b610 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1b620 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1b630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b640 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1b650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1b660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b670 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1b680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b6a0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1b6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b6c0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1b6d0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1b6e0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1b6f0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1b700 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1b710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b720 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1b730 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1b740 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1b750 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1b760 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1b770 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1b780 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1b790 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1b7a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1b7b0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1b7c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1b7d0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1b7e0 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43        9../*.** C
1b7f0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1b800 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1b810 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a  ent {F13010}.**.
1b820 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1b830 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1b840 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1b850 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1b860 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1b870 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1b880 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a  hese routines. .
1b890 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1b8a0 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73  argument "db" is
1b8b0 20 61 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   an [database co
1b8c0 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62  nnection] .** ob
1b8d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1b8e0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
1b8f0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b900 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b910 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
1b920 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20  _open16()]. .** 
1b930 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1b940 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68  ent "zSql" is th
1b950 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
1b960 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
1b970 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
1b980 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1b990 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
1b9a0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
1b9b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b9c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
1b9d0 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73  uses UTF-8 and s
1b9e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1b9f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1ba00 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
1ba10 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e   use UTF-16. {EN
1ba20 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  D}.**.** If the 
1ba30 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1ba40 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a  s less.** than z
1ba50 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
1ba60 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1ba70 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1ba80 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42  inator..** If nB
1ba90 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1baa0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1bab0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1bac0 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20  er of .** bytes 
1bad0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1bae0 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
1baf0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1bb00 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1bb10 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1bb20 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1bb30 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1bb40 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 74 68 65  acter or .** the
1bb50 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1bb60 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1bb70 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1bb80 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1bb90 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1bba0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1bbb0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1bbc0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1bbd0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1bbe0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 68  dvantage to be h
1bbf0 61 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ad by passing an
1bc00 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1bc10 20 74 68 61 74 20 0a 2a 2a 20 69 73 20 65 71 75   that .** is equ
1bc20 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1bc30 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1bc40 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1bc50 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a  >including</i> .
1bc60 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1bc70 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b 45 4e 44  nator bytes.{END
1bc80 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  }.**.** *pzTail 
1bc90 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1bca0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1bcb0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1bcc0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1bcd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1bce0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1bcf0 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1bd00 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1bd10 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1bd20 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1bd30 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1bd40 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1bd50 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1bd60 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1bd70 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1bd80 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1bd90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1bda0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1bdb0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1bdc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1bdd0 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 73    Or if there is
1bde0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
1bdf0 6d 74 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20  mt is.** set to 
1be00 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
1be10 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1be20 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1be30 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64   input.** is and
1be40 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
1be50 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1be60 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1be70 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33  to NULL..** {U13
1be80 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
1be90 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1bea0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1beb0 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  leting the.** co
1bec0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
1bed0 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ment.** using [s
1bee0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1bef0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1bf00 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1bf10 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
1bf20 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
1bf30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1bf40 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b  herwise an .** [
1bf50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1bf60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1bf70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1bf80 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
1bf90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1bfa0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
1bfb0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
1bfc0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
1bfd0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
1bfe0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
1bff0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
1c000 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1c010 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
1c020 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
1c030 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
1c040 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1c050 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1c060 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1c070 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1c080 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1c090 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1c0a0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1c0b0 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c  the .** original
1c0c0 20 53 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d   SQL text. {END}
1c0d0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
1c0e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c0f0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
1c100 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
1c110 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
1c120 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1c130 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
1c140 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1c150 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
1c160 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
1c170 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
1c180 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
1c190 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
1c1a0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1c1b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1c1c0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
1c1d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
1c1e0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
1c1f0 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
1c200 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
1c210 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
1c220 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
1c230 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
1c240 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
1c250 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
1c260 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
1c270 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
1c280 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
1c290 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
1c2a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  .** [SQLITE_SCHE
1c2b0 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74  MA] is now a fat
1c2c0 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
1c2d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1c2e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1c2f0 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1c300 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1c310 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1c320 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1c330 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1c340 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1c350 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1c360 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1c370 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1c380 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a   return. {END}.*
1c390 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1c3a0 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
1c3b0 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20  ror occurs, .** 
1c3c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c3d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1c3e0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1c3f0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
1c400 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1c410 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a  error codes]. .*
1c420 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68  * The legacy beh
1c430 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b  avior was that [
1c440 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c450 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1c460 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b  n a generic.** [
1c470 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1c480 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f  sult code and yo
1c490 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
1c4a0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1c4b0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
1c4c0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1c4d0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
1c4e0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1c4f0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1c500 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
1c510 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 72 66  " prepare interf
1c520 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1c530 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1c540 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20  the error is.** 
1c550 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1c560 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1c570 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
1c580 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c590 7b 46 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {F13011} The [sq
1c5a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1c5b0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1c5c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1c5d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c5e0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1c5f0 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1c600 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1c610 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1c620 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1c630 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
1c640 7b 46 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {F13012} The [sq
1c650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1c660 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1c670 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1c680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c690 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1c6a0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1c6b0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1c6c0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1c6d0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1c6e0 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
1c6f0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1c700 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
1c710 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
1c720 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1c730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c740 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1c750 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1c760 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1c770 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
1c780 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c  n zero, then SQL
1c790 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20   text is.**     
1c7a0 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a       read from z
1c7b0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1c7c0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1c7d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1c7e0 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20 74  ** {F13014} If t
1c7f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1c800 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1c810 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1c820 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
1c830 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
1c840 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
1c850 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1c860 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62  at most nBytes b
1c870 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
1c880 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
1c890 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
1c8a0 2a 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b  ** {F13015} In [
1c8b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c8c0 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
1c8d0 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
1c8e0 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
1c8f0 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
1c900 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1c910 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
1c920 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
1c930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1c940 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
1c950 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
1c960 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1c970 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
1c980 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
1c990 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1c9a0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1c9b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1c9c0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1c9d0 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
1c9e0 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
1c9f0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
1ca00 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
1ca10 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20  .**.** {F13016} 
1ca20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1ca30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
1ca40 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1ca50 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
1ca60 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
1ca70 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
1ca80 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
1ca90 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
1caa0 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
1cab0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1cac0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
1cad0 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a  pointer to NULL.
1cae0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 7a  **          if z
1caf0 53 71 6c 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74  Sql contains not
1cb00 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
1cb10 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
1cb20 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b  mments. .**.** {
1cb30 46 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c  F13019} The [sql
1cb40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cb50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
1cb60 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65   its variants re
1cb70 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
1cb80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1cb90 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
1cba0 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
1cbb0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
1cbc0 7b 46 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20  {F13021} Before 
1cbd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cbe0 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70  (db,zSql,nByte,p
1cbf0 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f  pStmt,pzTail)] o
1cc00 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  r its.**        
1cc10 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72    variants retur
1cc20 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79  ns an error (any
1cc30 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1cc40 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a  n [SQLITE_OK]).*
1cc50 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66 69  *          it fi
1cc60 72 73 74 20 73 65 74 73 20 2a 70 70 53 74 6d 74  rst sets *ppStmt
1cc70 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
1cc80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cc90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1cca0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1ccb0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1ccc0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1ccd0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1cce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1ccf0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1cd00 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1cd10 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1cd20 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1cd30 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1cd40 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1cd50 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1cd60 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1cd70 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1cd80 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1cd90 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1cda0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1cdb0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1cdc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1cdd0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1cde0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1cdf0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1ce00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ce10 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1ce20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1ce30 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1ce40 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ce50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ce60 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ce70 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ce80 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ce90 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1cea0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ceb0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1cec0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1ced0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1cee0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1cef0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1cf00 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1cf10 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1cf20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1cf30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1cf40 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1cf50 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1cf60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1cf70 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1cf80 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1cf90 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1cfa0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1cfb0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1cfc0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1cfd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1cfe0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1cff0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1d000 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d010 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1d020 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1d030 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1d040 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1d050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d060 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1d070 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1d080 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1d090 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1d0a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1d0b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1d0c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1d0d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1d0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1d0f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1d100 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1d110 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1d120 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1d130 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1d140 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d150 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1d160 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1d170 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1d180 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1d190 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1d1a0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1d1b0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46  Statement SQL {F
1d1c0 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13100}.**.** Thi
1d1d0 73 20 69 6e 74 65 72 66 61 63 65 20 20 63 61 6e  s interface  can
1d1e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1d1f0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1d200 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1d210 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1d220 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1d230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d240 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nt]..**.** INVAR
1d250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1d260 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72  3101} If the [pr
1d270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d280 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20  ] passed as .** 
1d290 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e 20           the an 
1d2a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1d2b0 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20  ite3_sql()] was 
1d2c0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20  compiled.**     
1d2d0 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73       compiled us
1d2e0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1d2f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d300 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1d310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d320 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20  e16_v2()],.**   
1d330 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
1d340 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63  ite3_sql()] func
1d350 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1d360 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20  ointer to a.**  
1d370 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1d380 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63  minated string c
1d390 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d  ontaining a UTF-
1d3a0 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20  8 rendering.**  
1d3b0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f          of the o
1d3c0 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74  riginal SQL stat
1d3d0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ement..**.** {F1
1d3e0 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72  3102} If the [pr
1d3f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d400 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20  ] passed as .** 
1d410 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e 20           the an 
1d420 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1d430 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20  ite3_sql()] was 
1d440 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20  compiled.**     
1d450 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73       compiled us
1d460 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1d470 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1d480 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1d490 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d4a0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1d4b0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1d4c0 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  ql()] function r
1d4d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1d4e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
1d4f0 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
1d500 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1d510 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73  lite3_sql(S)] is
1d520 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1d530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
1d540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d550 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75  ] S is deleted u
1d560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1d570 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63  nalize(S)]..*/.c
1d580 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1d590 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
1d5a0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1d5b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44  .** CAPI3REF:  D
1d5c0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
1d5d0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b   Value Object  {
1d5e0 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F15000}.** KEYWO
1d5f0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1d600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1d610 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1d620 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1d630 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1d640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1d650 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1d660 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1d670 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1d680 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1d690 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  e table..** SQLi
1d6a0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1d6b0 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76  typing for the v
1d6c0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1d6d0 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f    .** Values sto
1d6e0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
1d6f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61 6e  alue objects can
1d700 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65   be.** be intege
1d710 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
1d720 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
1d730 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
1d740 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
1d750 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1d760 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
1d770 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
1d780 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
1d790 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
1d7a0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
1d7b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1d7c0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
1d7d0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
1d7e0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
1d7f0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
1d800 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1d810 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
1d820 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1d830 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
1d840 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
1d850 20 73 70 65 63 69 66 69 65 73 20 0a 2a 2a 20 77   specifies .** w
1d860 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
1d870 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
1d880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1d890 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
1d8a0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
1d8b0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
1d8c0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
1d8d0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
1d8e0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
1d8f0 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
1d900 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
1d910 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1d920 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1d930 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
1d940 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
1d950 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1d960 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1d970 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
1d980 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
1d990 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
1d9a0 2a 20 28 77 69 74 68 20 53 51 4c 49 54 45 5f 54  * (with SQLITE_T
1d9b0 48 52 45 41 44 53 41 46 45 3d 30 20 61 6e 64 20  HREADSAFE=0 and 
1d9c0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
1d9d0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
1d9e0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e  rning 0).** then
1d9f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1da00 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1da10 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 61 6e  .** protected an
1da20 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  d unprotected sq
1da30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1da40 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1da50 20 62 65 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65   be.** used inte
1da60 72 63 68 61 6e 67 65 61 62 6c 65 2e 20 20 48 6f  rchangeable.  Ho
1da70 77 65 76 65 72 2c 20 66 6f 72 20 6d 61 78 69 6d  wever, for maxim
1da80 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1da90 69 74 79 20 69 74 0a 2a 2a 20 69 73 20 72 65 63  ity it.** is rec
1daa0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
1dab0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61 6b 65 20  plications make 
1dac0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1dad0 62 65 74 77 65 65 6e 0a 2a 2a 20 62 65 74 77 65  between.** betwe
1dae0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1daf0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1db00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1db10 74 73 20 65 76 65 6e 20 69 66 0a 2a 2a 20 74 68  ts even if.** th
1db20 65 79 20 61 72 65 20 73 69 6e 67 6c 65 20 74 68  ey are single th
1db30 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  readed..**.** Th
1db40 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1db50 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1db60 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1db70 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1db80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1db90 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   of application-
1dba0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1dbb0 74 69 6f 6e 73 20 61 72 65 20 70 72 6f 74 65 63  tions are protec
1dbc0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1dbd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1dbe0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1dbf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1dc00 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1dc10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1dc20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1dc30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1dc40 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1dc50 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1dc60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1dc70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1dc80 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20 41 6c 6c  d_value()].  All
1dc90 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
1dca0 61 63 65 73 20 74 68 61 74 20 75 73 65 20 73 71  aces that use sq
1dcb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 72 65 71 75  lite3_value requ
1dcc0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1dcd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1dce0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1dcf0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1dd00 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1dd10 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
1dd20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1dd30 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d   Object {F16001}
1dd40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
1dd50 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
1dd60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
1dd70 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
1dd80 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
1dd90 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
1dda0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
1ddb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ddc0 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c  .** object is al
1ddd0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1dde0 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  eter to applicat
1ddf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1de00 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79  functions..*/.ty
1de10 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1de20 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1de30 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1de40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1de50 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1de60 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1de70 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a  ments {F13500}.*
1de80 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
1de90 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
1dea0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1deb0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a  e_v2()] and its.
1dec0 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74  ** variants, lit
1ded0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1dee0 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d 65  lace by a parame
1def0 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66  ter in one.** of
1df00 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
1df10 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1df20 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
1df30 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
1df40 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
1df50 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
1df60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
1df70 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
1df80 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
1df90 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
1dfa0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20  literal,.** VVV 
1dfb0 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
1dfc0 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a  rameter name..**
1dfd0 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
1dfe0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
1dff0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
1e000 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1e010 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70  es".** or "SQL p
1e020 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1e030 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1e040 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1e050 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1e060 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1e070 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1e080 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1e090 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e0a0 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20  tines always.** 
1e0b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1e0c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1e0d0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1e0e0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1e0f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e100 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e110 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  s. The second.**
1e120 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1e130 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61   index of the pa
1e140 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1e150 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20  t. The.** first 
1e160 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1e170 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1e180 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1e190 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
1e1a0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
1e1b0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
1e1c0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
1e1d0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
1e1e0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
1e1f0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
1e200 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65  urrence. .** The
1e210 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1e220 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1e230 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1e240 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1e250 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e260 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66  r_name()] API if
1e270 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
1e280 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
1e290 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
1e2a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
1e2b0 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
1e2c0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1e2d0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f  een 1 and the co
1e2e0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61  mpile-time.** pa
1e2f0 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d  rameter SQLITE_M
1e300 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1e310 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  ER (default valu
1e320 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
1e330 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1e340 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
1e350 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
1e360 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
1e370 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69  n those.** routi
1e380 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1e390 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1e3a0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1e3b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1e3c0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61  s.** in the para
1e3d0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1e3e0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1e3f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1e400 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20  <u>bytes</u>.** 
1e410 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1e420 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1e430 63 68 61 72 61 63 74 65 72 73 2e 20 0a 2a 2a 20  characters. .** 
1e440 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1e450 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
1e460 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
1e470 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
1e480 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1e490 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
1e4a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1e4b0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
1e4c0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1e4d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1e4e0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1e4f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1e500 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1e510 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1e520 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1e530 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1e540 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1e550 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1e560 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1e570 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66  ith it. If the f
1e580 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
1e590 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
1e5a0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
1e5b0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
1e5c0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
1e5d0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
1e5e0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
1e5f0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
1e600 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
1e610 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
1e620 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20  ** If the fifth 
1e630 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1e640 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1e650 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1e660 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e670 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1e680 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1e690 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1e6a0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1e6b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e6c0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1e6d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1e6e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
1e6f0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
1e700 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
1e710 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
1e720 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  ed with zeros.  
1e730 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1e740 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1e750 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1e760 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1e770 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68  hold it size) wh
1e780 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
1e790 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
1e7a0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
1e7b0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
1e7c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1e7d0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
1e7e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
1e7f0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
1e800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1e810 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1e820 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
1e830 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76  tines. A negativ
1e840 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74  e.** value for t
1e850 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1e860 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1e870 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1e880 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1e890 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
1e8a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
1e8b0 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
1e8c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
1e8d0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
1e8e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1e8f0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
1e900 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
1e910 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
1e920 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1e930 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1e940 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1e950 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
1e960 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1e970 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1e980 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
1e990 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1e9a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1e9b0 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
1e9c0 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
1e9d0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1e9e0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
1e9f0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1ea00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1ea10 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1ea20 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
1ea30 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1ea40 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
1ea50 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
1ea60 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
1ea70 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
1ea80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1ea90 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
1eaa0 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
1eab0 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
1eac0 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
1ead0 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
1eae0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
1eaf0 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
1eb00 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
1eb10 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
1eb20 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
1eb30 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
1eb40 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
1eb50 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
1eb60 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
1eb70 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
1eb80 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
1eb90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1eba0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1ebb0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1ebc0 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
1ebd0 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
1ebe0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
1ebf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1ec00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ec10 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
1ec20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ec30 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1ec40 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1ec50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ec60 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1ec70 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1ec80 2a 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20  ** {F13506} The 
1ec90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eca0 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   | SQL statement
1ecb0 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
1ecc0 6e 69 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  nizes.**        
1ecd0 20 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20    tokens of the 
1ece0 66 6f 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e  forms "?", "?NNN
1ecf0 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
1ed00 22 2c 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a  ", and "@VVV".**
1ed10 20 20 20 20 20 20 20 20 20 20 61 73 20 53 51 4c            as SQL
1ed20 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65   parameters, whe
1ed30 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
1ed40 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
1ed50 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
1ed60 20 20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65    digits and whe
1ed70 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
1ed80 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
1ed90 20 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20   more .**       
1eda0 20 20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20     alphanumeric 
1edb0 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a  characters or ":
1edc0 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f  :" optionally fo
1edd0 6c 6c 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20  llowed by.**    
1ede0 20 20 20 20 20 20 61 20 73 74 72 69 6e 67 20 63        a string c
1edf0 6f 6e 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61  ontaining no spa
1ee00 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65  ces and containe
1ee10 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68  d within parenth
1ee20 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eses..**.** {F13
1ee30 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c  509} The initial
1ee40 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
1ee50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
1ee60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  LL..**.** {F1351
1ee70 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  2} The index of 
1ee80 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d  an "?" SQL param
1ee90 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67  eter is one larg
1eea0 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20  er than the.**  
1eeb0 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20          largest 
1eec0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
1eed0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65  ameter to the le
1eee0 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20  ft, or 1 if.**  
1eef0 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20          the "?" 
1ef00 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20  is the leftmost 
1ef10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  SQL parameter..*
1ef20 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68  *.** {F13515} Th
1ef30 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
1ef40 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74  NNN" SQL paramet
1ef50 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65  er is the intege
1ef60 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  r NNN..**.** {F1
1ef70 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20  3518} The index 
1ef80 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24  of an ":VVV", "$
1ef90 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20  VVV", or "@VVV" 
1efa0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1efb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1efc0 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64   same as the ind
1efd0 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f  ex of leftmost o
1efe0 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68  ccurrences of th
1eff0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
1f000 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72     parameter, or
1f010 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74   one more than t
1f020 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
1f030 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20   over all.**    
1f040 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
1f050 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20   to the left if 
1f060 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73  this is the firs
1f070 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20  t occurrence.** 
1f080 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73           of this
1f090 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31   parameter, or 1
1f0a0 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
1f0b0 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74  leftmost paramet
1f0c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  er..**.** {F1352
1f0d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1f0e0 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74  prepare | SQL st
1f0f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1f100 5d 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20  ] fail with.**  
1f110 20 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49          an [SQLI
1f120 54 45 5f 52 41 4e 47 45 5d 20 65 72 72 6f 72 20  TE_RANGE] error 
1f130 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
1f140 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1f150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f160 6c 65 73 73 20 74 68 61 6e 20 31 20 6f 72 20 67  less than 1 or g
1f170 72 65 61 74 65 72 20 74 68 61 6e 20 53 51 4c 49  reater than SQLI
1f180 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1f190 4e 55 4d 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46  NUMBER..**.** {F
1f1a0 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
1f1b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1f1c0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
1f1d0 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
1f1e0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
1f1f0 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
1f200 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
1f210 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
1f220 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
1f230 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
1f240 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f250 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
1f260 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
1f270 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1f280 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
1f290 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
1f2a0 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
1f2b0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
1f2c0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
1f2d0 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
1f2e0 0a 2a 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e  .** {F13530} Bin
1f2f0 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
1f300 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
1f310 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1f320 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
1f330 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
1f340 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
1f350 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1f360 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  t(S)]..**.** {F1
1f370 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
1f380 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1f390 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
1f3a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1f3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f3c0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
1f3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f3e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f3f0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
1f400 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
1f410 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
1f420 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
1f430 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 70  blob or string p
1f440 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
1f450 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
1f460 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
1f470 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  ve..**.** {F1353
1f480 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
1f490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1f4a0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
1f4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f4c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f4d0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
1f4e0 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
1f4f0 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
1f500 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
1f510 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1f520 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
1f530 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
1f540 0a 2a 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20  .** {F13539} In 
1f550 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1f560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1f570 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1f580 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1f590 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1f5a0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1f5b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1f5c0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1f5d0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
1f5e0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
1f5f0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
1f600 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1f610 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1f620 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
1f630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f640 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
1f650 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
1f660 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
1f670 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
1f680 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
1f690 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
1f6a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34  ng..**.** {F1354
1f6b0 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
1f6c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f6d0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
1f6e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f6f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1f700 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
1f710 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f720 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1f730 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
1f740 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
1f750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
1f760 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
1f770 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
1f780 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a  utine makes a .*
1f790 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61  *          priva
1f7a0 74 65 20 63 6f 70 79 20 6f 66 20 56 20 76 61 6c  te copy of V val
1f7b0 75 65 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  ue before it ret
1f7c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  urns..**.** {F13
1f7d0 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  545} In calls to
1f7e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f7f0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
1f800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f810 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1f820 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
1f830 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f840 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1f850 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
1f860 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72  n D is a pointer
1f870 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1f880 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  a function, SQLi
1f890 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20  te invokes that 
1f8a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74  function to dest
1f8b0 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  roy the.**      
1f8c0 20 20 20 20 56 20 76 61 6c 75 65 20 61 66 74 65      V value afte
1f8d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1f8e0 64 20 75 73 69 6e 67 20 74 68 65 20 56 20 76 61  d using the V va
1f8f0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  lue..**.** {F135
1f900 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  48} In calls to 
1f910 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
1f920 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d  roblob(S,N,V,L)]
1f930 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64   the value bound
1f940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1f950 61 20 62 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65  a blob of L byte
1f960 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  s, or a zero-len
1f970 67 74 68 20 62 6c 6f 62 20 69 66 20 4c 20 69 73  gth blob if L is
1f980 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   negative..**.**
1f990 20 7b 46 31 33 35 35 31 7d 20 49 6e 20 63 61 6c   {F13551} In cal
1f9a0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1f9b0 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29  ind_value(S,N,V)
1f9c0 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74  ] the V argument
1f9d0 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   may.**         
1f9e0 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70 72   be either a [pr
1f9f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fa00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72  value] object or
1fa10 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
1fa20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
1fa30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1fa40 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ct..*/.int sqlit
1fa50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
1fa60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1fa70 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1fa80 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1fa90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1faa0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
1fab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1fac0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
1fad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
1fae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1faf0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
1fb00 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
1fb10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fb20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
1fb30 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
1fb40 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
1fb50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
1fb60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1fb70 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
1fb80 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1fb90 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
1fba0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1fbb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1fbc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
1fbd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1fbe0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
1fbf0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1fc00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
1fc10 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
1fc20 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
1fc30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1fc40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1fc50 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
1fc60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1fc70 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
1fc80 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
1fc90 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20   SQL Parameters 
1fca0 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13600}.**.** T
1fcb0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
1fcc0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
1fcd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 53 51  the number of SQ
1fce0 4c 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L parameters.** 
1fcf0 69 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  in a prepared st
1fd00 61 74 65 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61  atement.  SQL pa
1fd10 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1fd20 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1fd30 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1fd40 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1fd50 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1fd60 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1fd70 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1fd80 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1fd90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1fda0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1fdb0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1fdc0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1fdd0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1fde0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
1fdf0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1fe00 68 65 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d  he largest param
1fe10 65 74 65 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c  eter..** For all
1fe20 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
1fe30 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
1fe40 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 20  rrespond to the 
1fe50 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69  number of.** uni
1fe60 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
1fe70 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
1fe80 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
1fe90 73 65 64 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a  sed, there may.*
1fea0 2a 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  * be gaps in the
1feb0 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
1fec0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1fed0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1fee0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1fef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff00 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1ff10 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1ff20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ff30 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
1ff40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1ff50 7b 46 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {F13601} The [sq
1ff60 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1ff70 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
1ff80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1ff90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ffa0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
1ffb0 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
1ffc0 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
1ffd0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1ffe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
1fff0 6f 72 20 30 20 69 66 20 53 0a 2a 2a 20 20 20 20  or 0 if S.**    
20000 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e        contains n
20010 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
20020 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20030 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20040 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
20050 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
20060 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
20070 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
20080 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13620}.**.** T
20090 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
200a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
200b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
200c0 20 6e 2d 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72   n-th.** SQL par
200d0 61 6d 65 74 65 72 20 69 6e 20 61 20 5b 70 72 65  ameter in a [pre
200e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
200f0 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
20100 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
20110 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
20120 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
20130 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
20140 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
20150 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
20160 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
20170 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
20180 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
20190 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
201a0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
201b0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
201c0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
201d0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
201e0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
201f0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
20200 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
20210 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
20220 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
20230 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
20240 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
20250 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
20260 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
20270 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20   If the value n 
20280 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
20290 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70  or if the n-th p
202a0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
202b0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
202c0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
202d0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
202e0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
202f0 73 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65  s in the UTF-8 e
20300 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
20310 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
20320 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
20330 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
20340 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
20350 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20360 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
20370 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20380 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
20390 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
203a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
203b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
203c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
203d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
203e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
203f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20400 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
20410 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
20420 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3621} The [sqlit
20430 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20440 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  r_name(S,N)] int
20450 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
20460 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46  *          a UTF
20470 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
20480 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20490 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
204a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
204b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
204c0 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78  ] S having index
204d0 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20   N, or.**       
204e0 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65     NULL if there
204f0 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d   is no SQL param
20500 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
20510 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20  N or if the.**  
20520 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
20530 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69  r with index N i
20540 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70  s an anonymous p
20550 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f  arameter "?"..*/
20560 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
20570 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20580 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
20590 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
205a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
205b0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
205c0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
205d0 20 4e 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a   Name {F13640}.*
205e0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
205f0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
20600 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
20610 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a  its name.  The.*
20620 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
20630 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
20640 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
20650 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
20660 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
20670 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20680 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20  te3_bind()].  A 
20690 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
206a0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
206b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
206c0 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61  found.  The para
206d0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
206e0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
206f0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
20700 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
20710 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
20720 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
20730 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
20740 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20750 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
20760 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
20770 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
20780 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
20790 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
207a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
207b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
207c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
207d0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
207e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
207f0 46 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c  F13641} The [sql
20800 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20810 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20  ter_index(S,N)] 
20820 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
20830 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
20840 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  e index of SQL p
20850 61 72 61 6d 65 74 65 72 20 69 6e 20 5b 70 72 65  arameter in [pre
20860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77  .**          S w
20880 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65  hose name matche
20890 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69  s the UTF-8 stri
208a0 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68  ng N, or 0 if th
208b0 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ere is.**       
208c0 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a     no match..*/.
208d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
208e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
208f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20900 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
20910 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
20920 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
20930 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
20940 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
20950 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F13660}.**.** C
20960 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
20970 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
20980 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
20990 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
209a0 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
209b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
209c0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
209d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
209e0 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69  ement].  Use thi
209f0 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20  s routine to.** 
20a00 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
20a10 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
20a20 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
20a30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
20a40 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
20a50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
20a60 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
20a70 73 65 74 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  sets all.**     
20a80 20 20 20 20 20 53 51 4c 20 70 61 72 61 6d 65 74       SQL paramet
20a90 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b  er bindings in [
20aa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20ab0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
20ac0 20 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a    back to NULL..
20ad0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
20ae0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
20af0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
20b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
20b10 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
20b20 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
20b30 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13710}.**.** 
20b40 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
20b50 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
20b60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
20b70 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a  eturned by the .
20b80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20b90 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
20ba0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a  utine returns 0.
20bb0 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20 61  ** if pStmt is a
20bc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
20bd0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
20be0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a  turn data (for .
20bf0 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50  ** example an UP
20c00 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  DATE)..**.** INV
20c10 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
20c20 46 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  F13711} The [sql
20c30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
20c40 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
20c50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
20c60 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
20c70 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
20c80 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
20c90 72 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  rated by the.** 
20ca0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
20cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
20cc0 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
20cd0 6e 6f 74 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20  not generate.** 
20ce0 20 20 20 20 20 20 20 20 20 61 20 72 65 73 75 6c           a resul
20cf0 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
20d00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
20d10 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
20d20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
20d30 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
20d40 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
20d50 6c 74 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a  lt Set {F13720}.
20d60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
20d70 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
20d80 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
20d90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
20da0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
20db0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
20dc0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
20dd0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
20de0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
20df0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
20e00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
20e10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20e20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  UTF8 string.** a
20e30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
20e40 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
20e50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
20e60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
20e70 64 0a 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e  d.** UTF16 strin
20e80 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
20e90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
20ea0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
20eb0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c  ement] that impl
20ec0 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43  ements the SELEC
20ed0 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  T statement..** 
20ee0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
20ef0 65 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75  eter is the colu
20f00 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  mn number.  The 
20f10 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
20f20 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e   is.** number 0.
20f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
20f40 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
20f50 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
20f60 6c 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a  l either the .**
20f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20f80 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
20f90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
20fa0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72  inalize()].** or
20fb0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
20fc0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
20fd0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
20fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20ff0 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20  e16().** on the 
21000 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
21010 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
21020 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
21030 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
21040 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
21050 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
21060 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
21070 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
21080 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
21090 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
210a0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
210b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
210c0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
210d0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
210e0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
210f0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
21100 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
21110 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
21120 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
21130 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
21140 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
21150 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
21160 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
21170 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
21180 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
21190 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
211a0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ext..**.** INVAR
211b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
211c0 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66  3721} A successf
211d0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
211e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
211f0 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a  lumn_name(S,N)].
21200 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
21210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
21220 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
21230 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f     of the Nth co
21240 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
21250 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   the left-most c
21260 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a  olumn) for the.*
21270 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
21280 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
21290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
212a0 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  as a.**         
212b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
212c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
212d0 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41 20  *.** {F13723} A 
212e0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
212f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
21300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
21310 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
21320 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
21330 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
21340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
21350 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
21360 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20 6c  where 0 is the l
21370 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  eft-most column)
21380 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
21390 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
213a0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
213b0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a  tement] S as a.*
213c0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
213d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
213e0 36 20 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20  6 string in the 
213f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
21400 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34  r..**.** {F13724
21410 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
21420 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
21430 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
21440 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20  n_name16()].**  
21450 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
21460 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
21470 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79   pointer if they
21480 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a   are unable to.*
21490 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
214a0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
214b0 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20  ld their normal 
214c0 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a  return strings..
214d0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49  **.** {F13725} I
214e0 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
214f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  r to [sqlite3_co
21500 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
21510 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
21520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
21530 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f  ame16(S,N)] is o
21540 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
21550 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
21560 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
21570 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
21580 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37  er..** .** {F137
21590 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
215a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
215b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
215c0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
215d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
215e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
215f0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
21600 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
21610 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
21620 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
21630 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
21640 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
21650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
21660 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
21670 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
21680 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alled..**.** {F1
21690 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
216a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
216b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
216c0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
216d0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
216e0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
216f0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
21700 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
21710 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
21720 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
21730 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
21740 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21750 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
21760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21770 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
21780 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21790 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
217a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
217b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
217c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
217d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
217e0 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13740}.**.** 
217f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
21800 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
21810 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
21820 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
21830 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
21840 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
21850 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  ult of a SELECT 
21860 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
21870 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
21880 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
21890 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
218a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
218b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
218c0 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31  r a UTF8 or UTF1
218d0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
218e0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
218f0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
21900 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
21910 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
21920 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
21930 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
21940 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
21950 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
21960 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
21970 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
21980 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
21990 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72  until.** the [pr
219a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
219b0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
219c0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
219d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
219e0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
219f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
21a00 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
21a10 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
21a20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
21a30 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
21a40 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
21a50 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
21a60 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
21a70 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
21a80 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
21a90 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
21aa0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
21ab0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
21ac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21ad0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
21ae0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
21af0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
21b00 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
21b10 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  n returned by .*
21b20 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
21b30 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
21b40 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
21b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
21b60 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
21b70 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
21b80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
21b90 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  n expression.** 
21ba0 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  or subquery and 
21bb0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
21bc0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
21bd0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
21be0 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c  ns.** return NUL
21bf0 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
21c00 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
21c10 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
21c20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
21c30 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
21c40 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
21c50 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a  y return the .**
21c60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
21c70 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
21c80 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
21c90 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
21ca0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73  lt.** column was
21cb0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
21cc0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
21cd0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
21ce0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
21cf0 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
21d00 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
21d10 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
21d20 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
21d30 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
21d40 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
21d50 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
21d60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
21d70 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
21d80 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
21d90 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  he .** SQLITE_EN
21da0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
21db0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
21dc0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
21dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  ..**.** {U13751}
21de0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
21df0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
21e00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
21e10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
21e20 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
21e30 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
21e40 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
21e50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
21e60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
21e70 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
21e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
21e90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
21ea0 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  741} The [sqlite
21eb0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
21ec0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
21ed0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
21ee0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
21ef0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
21f00 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
21f10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
21f20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
21f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
21f40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
21f50 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21f60 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
21f70 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
21f80 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
21f90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
21fa0 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
21fb0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
21fc0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
21fd0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
21fe0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
21ff0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
22000 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
22010 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54    .** {F13742} T
22020 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
22030 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
22040 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
22050 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
22060 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
22070 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
22080 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
22090 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
220a0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
220b0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
220c0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
220d0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
220e0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
220f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22100 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
22110 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
22120 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
22130 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
22140 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
22150 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
22160 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
22170 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
22180 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
22190 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
221a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
221b0 20 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {F13743} The [s
221c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
221d0 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
221e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
221f0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
22200 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
22210 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
22220 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
22230 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
22240 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
22250 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
22260 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22270 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
22280 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
22290 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
222a0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
222b0 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
222c0 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
222d0 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
222e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
222f0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
22300 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
22310 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
22320 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 68   .** {F13744} Th
22330 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22340 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
22350 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
22360 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
22370 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
22380 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
22390 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
223a0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
223b0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
223c0 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20  able from which 
223d0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
223e0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
223f0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
22400 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
22410 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
22420 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
22430 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
22440 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
22450 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
22460 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
22470 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
22480 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
22490 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
224a0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
224b0 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
224c0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
224d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
224e0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
224f0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
22500 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
22510 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
22520 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
22530 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
22540 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
22550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
22560 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
22570 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
22580 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
22590 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
225a0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
225b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
225c0 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
225d0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
225e0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
225f0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
22600 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
22610 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
22620 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
22630 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54    .** {F13746} T
22640 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
22650 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
22660 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
22670 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
22680 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22690 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
226a0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
226b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
226c0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
226d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
226e0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
226f0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
22700 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
22710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22720 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
22730 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
22740 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
22750 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
22760 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
22770 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
22780 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
22790 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
227a0 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
227b0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
227c0 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  e..**          .
227d0 2a 2a 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20  ** {F13748} The 
227e0 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72  return values fr
227f0 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
22800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22810 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c  atabase_name|col
22820 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
22830 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
22840 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 0a 2a       are valid.*
22850 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74  *          for t
22860 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
22870 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22880 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
22890 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65      or until the
228a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61   encoding is cha
228b0 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20  nged by another 
228c0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
228d0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
228e0 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
228f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
22900 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
22910 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
22920 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31  S:.**.** {U13751
22930 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  } If two or more
22940 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
22950 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
22960 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
22970 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
22980 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  ame|column metad
22990 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
229a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
229b0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
229c0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
229d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
229e0 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
229f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
22a00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22a10 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
22a20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22a30 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
22a40 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
22a50 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
22a60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22a70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
22a80 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
22a90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
22aa0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
22ab0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
22ac0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
22ad0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
22ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
22af0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
22b00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22b10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22b20 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
22b30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
22b40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
22b50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22b60 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
22b70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22b80 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
22b90 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
22ba0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
22bb0 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37  ery Result {F137
22bc0 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  60}.**.** The fi
22bd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22be0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22bf0 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20  tement]. .** If 
22c00 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
22c10 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  s a SELECT state
22c20 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
22c30 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a   column of the .
22c40 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
22c50 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53  lt set of that S
22c60 45 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65  ELECT is a table
22c70 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
22c80 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
22c90 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
22ca0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
22cb0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
22cc0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
22cd0 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74  rned.  If the Nt
22ce0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
22cf0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
22d00 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
22d10 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
22d20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
22d30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
22d40 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
22d50 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
22d60 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45  F-8 encoded.  {E
22d70 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ND} .** For exam
22d80 70 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61  ple, in the data
22d90 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
22da0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
22db0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
22dc0 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f  **.** And the fo
22dd0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
22de0 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  t compiled:.**.*
22df0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
22e00 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
22e10 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75  ** Then this rou
22e20 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
22e30 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
22e40 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
22e50 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20  econd.** result 
22e60 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
22e70 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
22e80 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
22e90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
22ea0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
22eb0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
22ec0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
22ed0 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
22ee0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
22ef0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
22f00 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
22f10 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
22f20 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
22f30 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
22f40 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
22f50 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
22f60 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
22f70 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
22f80 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
22f90 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
22fa0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
22fb0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
22fc0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
22fd0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
22fe0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
22ff0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
23000 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
23010 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
23020 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31  S:.**.** {F13761
23030 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
23040 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
23050 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
23060 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
23070 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65      returns a ze
23080 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
23090 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
230a0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  ining the.**    
230b0 20 20 20 20 20 20 20 74 68 65 20 64 65 63 6c 61         the decla
230c0 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
230d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
230e0 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
230f0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
23100 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
23110 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
23120 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
23130 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
23140 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
23150 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
23160 2a 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73  ** {F13762}  A s
23170 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
23180 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
23190 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
231a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
231b0 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
231c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
231d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
231e0 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
231f0 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
23200 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
23210 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
23220 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
23230 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
23240 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
23250 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
23260 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
23270 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
23280 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
23290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
232a0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
232b0 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
232c0 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
232d0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
232e0 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
232f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
23300 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23310 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  in [prepared sta
23320 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
23330 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
23340 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
23350 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
23360 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
23370 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
23380 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
23390 6f 6c 75 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65  olumn or if a me
233a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
233b0 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20  failure.**      
233c0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
233d0 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76  ng encoding conv
233e0 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a  ersions, then.**
233f0 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73             calls
23400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
23410 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
23420 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
23430 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
23440 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c  mn_decltype16(S,
23450 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  N)] return NULL.
23460 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
23470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23480 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
23490 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
234a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
234b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
234c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
234d0 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41  int);../* .** CA
234e0 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74  PI3REF:  Evaluat
234f0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
23500 6e 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a  nt {F13200}.**.*
23510 2a 20 41 66 74 65 72 20 61 6e 20 5b 70 72 65 70  * After an [prep
23520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23530 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
23540 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a  d with a call.**
23550 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69   to either [sqli
23560 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23570 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
23580 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
23590 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68   to one of.** th
235a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
235b0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
235c0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
235d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
235e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66  ,.** then this f
235f0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
23600 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
23610 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
23620 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61  uate the .** sta
23630 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
23640 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
23650 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
23660 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  s sqlite3_step()
23670 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
23680 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
23690 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
236a0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
236b0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
236c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
236d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
236e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
236f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
23700 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
23710 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
23720 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
23730 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
23740 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
23750 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
23760 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
23770 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
23780 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
23790 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
237a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
237b0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
237c0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
237d0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
237e0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
237f0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
23800 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
23810 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
23820 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  Y], .** [SQLITE_
23830 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
23840 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
23850 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
23860 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
23870 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
23880 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
23890 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  other [SQLITE_OK
238a0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a   | result code].
238b0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
238c0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
238d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
238e0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
238f0 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a  ed as.** well..*
23900 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
23910 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
23920 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
23930 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
23940 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
23950 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
23960 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
23970 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
23980 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d  atement is a COM
23990 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  MIT.** or occurs
239a0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
239b0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
239c0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
239d0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
239e0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
239f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
23a00 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20  ot a COMMIT and 
23a10 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
23a20 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
23a30 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
23a40 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
23a50 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
23a60 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
23a70 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
23a80 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
23a90 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
23aa0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
23ab0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
23ac0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
23ad0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
23ae0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
23af0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
23b00 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
23b10 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
23b20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
23b30 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
23b40 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
23b50 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
23b60 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
23b70 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
23b80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
23b90 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
23ba0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
23bb0 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54   then .** [SQLIT
23bc0 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e  E_ROW] is return
23bd0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
23be0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
23bf0 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70  s ready.** for p
23c00 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
23c10 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
23c20 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
23c30 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  sed using.** the
23c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23c50 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63  _int | column ac
23c60 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
23c70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
23c80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
23c90 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
23ca0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
23cb0 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c  ata..** .** [SQL
23cc0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
23cd0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
23ce0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
23cf0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
23d00 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
23d10 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
23d20 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
23d30 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
23d40 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
23d50 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
23d60 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
23d70 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
23d80 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
23d90 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
23da0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
23db0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
23dc0 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65  or code (example
23dd0 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  :.** [SQLITE_INT
23de0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
23df0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
23e00 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
23e10 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
23e20 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
23e30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
23e40 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
23e50 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23e60 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
23e70 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
23e80 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
23e90 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
23ea0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
23eb0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
23ec0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
23ed0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
23ee0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
23ef0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
23f00 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
23f10 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
23f20 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
23f30 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
23f40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
23f50 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
23f60 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
23f70 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
23f80 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
23f90 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f  t had .** previo
23fa0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
23fb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
23fc0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
23fd0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
23fe0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
23ff0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
24000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
24010 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
24020 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
24030 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
24040 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
24050 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
24060 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
24070 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  </b>.** In the l
24080 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
24090 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33   .** the sqlite3
240a0 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61  _step() API alwa
240b0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
240c0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
240d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
240e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
240f0 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  y error other th
24100 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
24110 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
24120 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
24130 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  st call [sqlite3
24140 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
24150 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24160 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
24170 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
24180 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72   specific.** [er
24190 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
241a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
241b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
241c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
241d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
241e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
241f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
24200 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
24210 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
24220 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
24230 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
24240 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
24250 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
24260 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
24270 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
24280 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
24290 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
242a0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
242b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
242c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
242d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20  ], then the .** 
242e0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
242f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
24300 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
24310 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
24320 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
24330 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
24340 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
24350 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
24360 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
24370 46 31 33 32 30 32 7d 20 20 49 66 20 5b 70 72 65  F13202}  If [pre
24380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24390 20 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62   S is ready to b
243a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  e.**           r
243b0 75 6e 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  un, then [sqlite
243c0 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e  3_step(S)] advan
243d0 63 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65  ces that prepare
243e0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  d statement.**  
243f0 20 20 20 20 20 20 20 20 20 75 6e 74 69 6c 20 74           until t
24400 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20  o completion or 
24410 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
24420 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
24430 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
24440 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
24450 6c 74 20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74  lt set or an int
24460 65 72 72 75 70 74 20 6f 72 20 72 75 6e 2d 74 69  errupt or run-ti
24470 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  me error occurs.
24480 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20  .**.** {F15304} 
24490 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
244a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
244b0 5d 20 63 61 75 73 65 73 20 74 68 65 20 0a 2a 2a  ] causes the .**
244c0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
244d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
244e0 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
244f0 6c 65 74 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20  letion,.**      
24500 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f       the functio
24510 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
24520 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
24530 46 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20  F15306}  When a 
24540 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
24550 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20  _step(S)] stops 
24560 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65  because it is re
24570 61 64 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ady.**          
24580 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
24590 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  er row of the re
245a0 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74  sult set, it ret
245b0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
245c0 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a    [SQLITE_ROW]..
245d0 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20  **.** {F15308}  
245e0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
245f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65  lite3_step(S)] e
24600 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20  ncounters an.** 
24610 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24620 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74  e3_interrupt|int
24630 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
24640 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20  -time error,.** 
24650 20 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74            it ret
24660 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
24670 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  ate error code t
24680 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  hat is not one o
24690 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  f.**           [
246a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c  SQLITE_OK], [SQL
246b0 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51  ITE_ROW], or [SQ
246c0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
246d0 2a 20 7b 46 31 35 33 31 30 7d 20 20 49 66 20 61  * {F15310}  If a
246e0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
246f0 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20  rupt|interrupt] 
24700 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f  or run-time erro
24710 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  r.**           o
24720 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63  ccurs during a c
24730 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24740 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20  step(S)].**     
24750 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65        for a [pre
24760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24770 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67   S created using
24780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65  .**           le
24790 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
247a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
247b0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
247c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
247d0 70 61 72 65 31 36 28 29 5d 20 74 68 65 6e 20 74  pare16()] then t
247e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
247f0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
24800 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
24810 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERROR], [SQLITE_
24820 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BUSY], or [SQLIT
24830 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e  E_MISUSE]..*/.in
24840 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
24850 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
24860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24870 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
24880 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
24890 74 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a  t {F13770}.**.**
248a0 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
248b0 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20  er of values in 
248c0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
248d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
248e0 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
248f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
24900 37 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c  71}  After a cal
24910 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
24920 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75  ep(S)] that retu
24930 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
24940 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
24950 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  he [sqlite3_data
24960 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69  _count(S)] routi
24970 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ne.**           
24980 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
24990 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68  same value as th
249a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
249b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
249c0 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f  ount(S)] functio
249d0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32  n..**.** {F13772
249e0 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65  }  After [sqlite
249f0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72  3_step(S)] has r
24a00 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75  eturned any valu
24a10 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
24a20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
24a30 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65  E_ROW] or before
24a40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
24a50 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20  )] has been .** 
24a60 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64            called
24a70 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
24a80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
24a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
24aa0 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e  e first time sin
24ab0 63 65 20 69 74 20 77 61 73 20 5b 73 71 6c 69 74  ce it was [sqlit
24ac0 65 33 5f 70 72 65 70 61 72 65 7c 70 72 65 70 61  e3_prepare|prepa
24ad0 72 65 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  red].**         
24ae0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65    or [sqlite3_re
24af0 73 65 74 7c 72 65 73 65 74 5d 2c 20 74 68 65 20  set|reset], the 
24b00 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
24b10 75 6e 74 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  unt(S)].**      
24b20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 72 65 74       routine ret
24b30 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
24b40 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
24b50 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
24b60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
24b70 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
24b80 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
24b90 73 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45  s {F10265}.** KE
24ba0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
24bb0 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36  EXT.**.** {F1026
24bc0 36 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  6}Every value in
24bd0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
24be0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
24bf0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
24c00 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
24c10 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
24c20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
24c30 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
24c40 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
24c50 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
24c60 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
24c70 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
24c80 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
24c90 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
24ca0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
24cb0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
24cc0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
24cd0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
24ce0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
24cf0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
24d00 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
24d10 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
24d20 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
24d30 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
24d40 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
24d50 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
24d60 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
24d70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
24d80 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
24d90 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53  E3_TEXT not.** S
24da0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
24db0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
24dc0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
24dd0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
24de0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
24df0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
24e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
24e10 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
24e20 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
24e30 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
24e40 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
24e50 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
24e60 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
24e70 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
24e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24e90 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73  : Results Values
24ea0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46   From A Query {F
24eb0 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13800}.**.** The
24ec0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
24ed0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
24ee0 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
24ef0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
24f00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
24f10 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
24f20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  .** a single col
24f30 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
24f40 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  nt result row of
24f50 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
24f60 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  ery.** case the 
24f70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
24f80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
24f90 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
24fa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
24fb0 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61   is being.** eva
24fc0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
24fd0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74  ite3_stmt*] that
24fe0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
24ff0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
25000 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
25010 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
25020 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65  ants) and.** the
25030 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
25040 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
25050 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
25060 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
25070 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  n .** should be 
25080 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
25090 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
250a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
250b0 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65  t.** has an inde
250c0 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  x of 0..**.** If
250d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
250e0 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  nt is not curren
250f0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
25100 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
25110 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d  the.** the colum
25120 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
25130 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
25140 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
25150 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  . .** These rout
25160 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
25170 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
25180 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
25190 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
251a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
251b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
251c0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
251d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
251e0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
251f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73  _finalize()] has
25200 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65   been call subse
25210 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
25220 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
25230 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
25240 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
25250 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
25260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25270 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
25280 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
25290 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
252a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
252b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
252c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
252d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
252e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
252f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
25300 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
25310 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
25320 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
25330 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
25340 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
25350 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
25360 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
25370 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
25380 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
25390 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c    .**.** The sql
253a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
253b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
253c0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  ns .** [SQLITE_I
253d0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
253e0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
253f0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
25400 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
25410 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
25420 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
25430 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
25440 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
25450 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
25460 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
25470 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
25480 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
25490 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
254a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
254b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
254c0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
254d0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
254e0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
254f0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
25500 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
25510 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
25520 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
25530 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
25540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25550 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
25560 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
25570 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
25580 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
25590 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
255a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
255b0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
255c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
255d0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
255e0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
255f0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
25600 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
25610 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
25620 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74   .** routine ret
25630 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
25640 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
25650 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
25660 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
25670 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
25680 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
25690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
256a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
256b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
256c0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
256d0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
256e0 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
256f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
25700 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
25710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25720 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
25730 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
25740 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
25750 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
25760 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
25770 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
25780 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25790 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
257a0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
257b0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
257c0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
257d0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
257e0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
257f0 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
25800 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
25810 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
25820 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
25830 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
25840 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
25850 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
25860 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
25870 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
25880 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
25890 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
258a0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
258b0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
258c0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
258d0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
258e0 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
258f0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
25900 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
25910 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
25920 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62  h blob is an arb
25930 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
25940 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
25950 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
25960 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
25980 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
25990 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
259a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
259b0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
259c0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
259d0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
259e0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
259f0 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20   of UTF-8.  .** 
25a00 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
25a10 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
25a20 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
25a30 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
25a40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
25a50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25a60 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
25a70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
25a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25a90 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
25aa0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25ab0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
25ac0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
25ad0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
25ae0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
25af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
25b00 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
25b10 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
25b20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25b30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
25b40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
25b50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
25b60 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
25b70 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
25b80 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
25b90 75 74 69 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20  utines like .** 
25ba0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
25bb0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
25bc0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
25bd0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
25be0 5f 62 79 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68  _bytes()],.** th
25bf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25c00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25c10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25c20 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
25c30 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
25c40 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
25c50 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
25c60 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
25c70 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
25c80 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
25c90 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
25ca0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
25cb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
25cc0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
25cd0 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65  rnally to do the
25ce0 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61   conversion.** a
25cf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
25d00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
25d10 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
25d20 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a  onversions that.
25d30 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  ** are applied:.
25d40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
25d50 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
25d60 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
25d70 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
25d80 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
25d90 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
25da0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
25db0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
25dc0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
25dd0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
25de0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
25df0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
25e00 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
25e10 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
25e20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
25e30 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
25e40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
25e50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
25e60 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
25e70 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
25e80 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
25e90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
25ea0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
25eb0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
25ec0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
25ed0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
25ee0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
25ef0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
25f00 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
25f10 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
25f20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
25f30 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
25f40 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
25f50 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
25f60 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
25f70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
25f80 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
25f90 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
25fa0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
25fb0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
25fc0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
25fd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
25fe0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
25ff0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
26000 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26010 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
26020 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
26030 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
26040 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
26050 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
26060 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
26070 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
26080 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26090 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
260a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
260b0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
260c0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
260d0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
260e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
260f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
26100 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
26110 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
26120 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26130 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26140 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26150 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26160 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
26170 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
26180 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26190 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
261a0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
261b0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
261c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
261d0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
261e0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
261f0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
26200 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
26210 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
26220 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
26230 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
26240 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
26250 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
26260 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
26270 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
26280 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
26290 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
262a0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
262b0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
262c0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
262d0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
262e0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
262f0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
26300 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
26310 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
26320 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
26330 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
26340 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
26350 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
26360 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
26370 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26380 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
26390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
263a0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
263b0 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65  idated. .** Type
263c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
263d0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
263e0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
263f0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
26400 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
26410 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
26420 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
26430 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
26440 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
26450 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a  olumn_text() .**
26460 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c            or sql
26470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26480 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
26490 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
264a0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
264b0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
264c0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
264d0 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  ing.</p></li>.**
264e0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
264f0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
26500 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
26510 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
26520 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
26530 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
26540 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26550 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
26560 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
26570 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
26580 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
26590 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  16.</p></li>.**.
265a0 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
265b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
265c0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
265d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
265e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
265f0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
26600 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
26610 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
26620 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
26630 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
26640 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
26650 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  p></li>.** </ul>
26660 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
26670 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
26680 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
26690 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
266a0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
266b0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
266c0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
266d0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
266e0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
266f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
26700 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
26710 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
26720 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
26730 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
26740 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
26750 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
26760 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
26770 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
26780 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74   but sometime it
26790 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
267a0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
267b0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
267c0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
267d0 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  dated.  .**.** T
267e0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
267f0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
26800 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
26810 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
26820 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
26830 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
26840 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c  ways:.**.**  <ul
26850 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
26860 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
26870 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
26880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26890 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
268a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
268b0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
268c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
268d0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
268e0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
268f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
26900 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
26910 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
26920 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c  ()</li>.**  </ul
26930 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
26940 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
26950 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
26960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73  column_text(), s
26970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26980 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69  ob(),.** or sqli
26990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
269a0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
269b0 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  ce the result in
269c0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a  to the desired.*
269d0 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  * format, then i
269e0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
269f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20  lumn_bytes() or 
26a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26a10 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66  ytes16() to.** f
26a20 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
26a30 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
26a40 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20  not mix call to 
26a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26a60 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ext() or.** sqli
26a70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
26a80 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
26a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26aa0 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64  ytes16().  And d
26ab0 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c  o not.** mix cal
26ac0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
26ad0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69  lumn_text16() wi
26ae0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
26af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26b00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
26b10 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
26b20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
26b30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
26b40 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
26b50 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
26b60 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
26b70 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
26b80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
26b90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
26ba0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
26bb0 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
26bc0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
26bd0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
26be0 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65  nd blobs is free
26bf0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
26c00 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
26c10 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
26c20 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
26c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26c40 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
26c50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
26c60 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73  etc. into .** [s
26c70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
26c80 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
26c90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
26ca0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
26cb0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
26cc0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
26cd0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
26ce0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
26cf0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
26d00 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
26d10 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
26d20 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
26d30 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
26d40 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
26d50 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
26d60 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
26d70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
26d80 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
26d90 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
26da0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
26db0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
26dc0 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  13803} The [sqli
26dd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
26de0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
26df0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
26e00 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
26e10 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
26e20 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
26e30 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
26e40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
26e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26e60 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20  into a blob and 
26e70 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a  then returns a.*
26e80 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
26e90 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
26ea0 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
26eb0 20 7b 46 31 33 38 30 36 7d 20 54 68 65 20 5b 73   {F13806} The [s
26ec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26ed0 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  tes(S,N)] interf
26ee0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
26ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
26f00 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26f10 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e  he blob or strin
26f20 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
26f30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26f40 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
26f50 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
26f60 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
26f70 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
26f80 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
26f90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26fa0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
26fb0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
26fc0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26fd0 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a  n_text(S,N)]..**
26fe0 0a 2a 2a 20 7b 46 31 33 38 30 39 7d 20 54 68 65  .** {F13809} The
26ff0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27000 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69  _bytes16(S,N)] i
27010 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27020 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27030 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27040 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
27050 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
27060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
27070 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
27080 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
27090 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
270a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
270b0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
270c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
270d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
270e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32  ]..**.** {F13812
270f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
27100 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e  olumn_double(S,N
27110 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
27120 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
27130 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
27140 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
27150 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
27160 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
27170 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
27180 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
27190 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
271a0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
271b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
271c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
271d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
271e0 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
271f0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
27200 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
27210 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
27220 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
27230 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
27240 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
27250 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
27260 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
27270 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
27280 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
27290 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
272a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
272b0 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
272c0 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
272d0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eger..**.** {F13
272e0 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
272f0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
27300 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
27310 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
27320 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
27330 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
27340 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
27350 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
27360 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
27370 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27380 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
27390 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
273a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
273b0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
273c0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
273d0 2a 20 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b  * {F13821} The [
273e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
273f0 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ext(S,N)] interf
27400 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
27410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
27420 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
27430 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
27440 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
27450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
27460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27470 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
27480 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
27490 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74   .**          st
274a0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
274b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
274c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
274d0 20 7b 46 31 33 38 32 34 7d 20 54 68 65 20 5b 73   {F13824} The [s
274e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
274f0 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  xt16(S,N)] inter
27500 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
27510 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
27520 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
27530 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
27540 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
27550 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
27560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27570 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
27580 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
27590 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
275a0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
275b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
275c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
275d0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
275e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
275f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
27600 46 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c  F13827} The [sql
27610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
27620 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27630 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
27640 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
27650 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
27660 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
27670 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
27680 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
27690 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
276a0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
276b0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
276c0 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20          the Nth 
276d0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
276e0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
276f0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
27700 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
27710 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27720 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33   S..**.** {F1383
27730 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
27740 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e  column_value(S,N
27750 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27760 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
27770 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e     pointer to an
27780 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27790 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
277a0 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ect for the.**  
277b0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
277c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
277d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
277e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
277f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
27800 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
27810 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
27820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27830 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
27840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
27850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27860 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
27870 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27890 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
278a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
278b0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
278c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
278d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
278e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
278f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
27900 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
27910 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
27920 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
27930 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
27940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27950 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
27960 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
27970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27980 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
27990 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
279a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
279b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
279c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
279d0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
279e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
279f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27a00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
27a10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
27a20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
27a30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27a40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
27a50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
27a60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
27a70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
27a80 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13300}.**.** The
27a90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27aa0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
27ab0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
27ac0 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
27ad0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20   statement]. If 
27ae0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
27af0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75  s.** executed su
27b00 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e  ccessfully, or n
27b10 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
27b20 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ll, then SQLITE_
27b30 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
27b40 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  ** If execution 
27b50 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
27b60 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
27b70 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
27b80 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
27b90 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
27ba0 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  returned. .**.**
27bb0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
27bc0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
27bd0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
27be0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
27bf0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27c00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
27c10 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
27c20 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a  chine has not .*
27c30 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
27c40 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
27c50 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
27c60 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
27c70 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
27c80 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69  an error or an i
27c90 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20  nterrupt.  (See 
27ca0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
27cb0 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f  pt()].) .** Inco
27cc0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
27cd0 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
27ce0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
27cf0 6e 73 20 63 61 6e 63 65 6c 65 64 2c 20 20 0a 2a  ns canceled,  .*
27d00 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
27d10 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
27d20 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65  , and the .** [e
27d30 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
27d40 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
27d50 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
27d60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
27d70 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65  .** {F11302} The
27d80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27d90 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  ze(S)] interface
27da0 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a   destroys the.**
27db0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
27dc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27dd0 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c   and releases al
27de0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  l.**          me
27df0 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65  mory and file re
27e00 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20  sources held by 
27e10 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  that object..**.
27e20 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74  ** {F11304} If t
27e30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
27e40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27e50 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
27e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
27e70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27e80 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20  ] S returned an 
27e90 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
27ea0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
27eb0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65  _finalize(S)] re
27ec0 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20  turns that same 
27ed0 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
27ee0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
27ef0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27f00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27f10 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
27f20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27f30 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d   Object {F13330}
27f40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27f50 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
27f60 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
27f70 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72   reset a .** [pr
27f80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27f90 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63  ] object..** bac
27fa0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
27fb0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
27fc0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
27fd0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
27fe0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
27ff0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
28000 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
28010 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
28020 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
28030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28040 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
28050 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
28060 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
28070 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
28080 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
28090 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  gs..**.** {F1133
280a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
280b0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
280c0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
280d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
280e0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
280f0 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
28100 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
28110 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rogram..**.** {F
28120 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
28130 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28140 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
28150 53 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20  S)] for .**     
28160 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28170 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
28180 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
28190 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
281a0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
281b0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
281c0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
281d0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
281e0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
281f0 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
28200 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
28210 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
28220 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  K]..**.** {F1133
28230 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
28240 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
28250 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
28260 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
28270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28280 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
28290 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
282a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
282b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
282c0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
282d0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
282e0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  e]..**.** {F1133
282f0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
28300 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
28310 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
28320 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
28330 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
28340 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
28350 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
28360 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
28370 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
28380 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
28390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
283a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
283b0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
283c0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
283d0 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a  ctions {F16100}.
283e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
283f0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
28400 72 6f 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a  routines} .**.**
28410 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
28420 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
28430 6c 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22  ly known as.** "
28440 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
28450 6e 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65  n routines") are
28460 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
28470 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
28480 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74  gregates.** or t
28490 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
284a0 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74  ehavior of exist
284b0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
284c0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
284d0 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65    The.** differe
284e0 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e  nce only between
284f0 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74   the two is that
28500 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
28510 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61  meter, the.** na
28520 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
28530 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  r) function or a
28540 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
28550 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
28560 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
28570 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
28580 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71  nd UTF-16 for sq
28590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
285a0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
285b0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
285c0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
285d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
285e0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
285f0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
28600 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
28610 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70  If a single.** p
28620 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
28630 20 74 68 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62   than one [datab
28640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28650 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
28660 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
28670 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
28680 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20  individually to 
28690 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
286a0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
286b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
286c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
286d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
286e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
286f0 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66  ated.** or redef
28700 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e  ined..** The len
28710 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
28720 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
28730 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
28740 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65  ve of the .** ze
28750 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
28760 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
28770 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
28780 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
28790 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
287a0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
287b0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
287c0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
287d0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
287e0 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45  ult in an SQLITE
287f0 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a  _ERROR error..**
28800 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
28810 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
28820 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
28830 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
28840 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
28850 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
28860 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
28870 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
28880 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
28890 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
288a0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
288b0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
288c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
288d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
288e0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
288f0 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20  cifies what .** 
28900 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
28910 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
28920 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
28930 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
28940 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
28950 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
28960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28970 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
28980 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
28990 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
289a0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
289b0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
289c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
289d0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
289e0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
289f0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
28a00 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
28a10 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
28a20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28a30 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
28a40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28a50 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
28a60 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
28a70 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
28a80 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
28a90 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
28aa0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
28ab0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
28ac0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
28ad0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
28ae0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
28af0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
28b00 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
28b10 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
28b20 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
28b30 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
28b40 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
28b50 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
28b60 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
28b70 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
28b80 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  at.** text encod
28b90 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
28ba0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
28bb0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a  ument should be.
28bc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  ** [SQLITE_ANY].
28bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
28be0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
28bf0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
28c00 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
28c10 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
28c20 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  e function can g
28c30 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
28c40 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
28c50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  .** [sqlite3_use
28c60 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
28c70 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
28c80 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
28c90 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
28ca0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
28cb0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
28cc0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
28cd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
28ce0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
28cf0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f  QL.** function o
28d00 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  r aggregate. A s
28d10 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
28d20 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
28d30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28d40 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61  .** the xFunc ca
28d50 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
28d60 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
28d70 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
28d80 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  he xStep.** and 
28d90 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  xFinal parameter
28da0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
28db0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
28dc0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
28dd0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53  ntation.** of xS
28de0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  tep and xFinal a
28df0 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
28e00 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
28e10 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
28e20 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c  .** existing SQL
28e30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
28e40 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
28e50 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
28e60 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
28e70 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  backs..**.** It 
28e80 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
28e90 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
28ea0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
28eb0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
28ec0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
28ed0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
28ee0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
28ef0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
28f00 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
28f10 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
28f20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
28f30 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
28f40 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
28f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
28f60 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
28f70 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
28f80 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
28f90 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
28fa0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
28fb0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33  S:.**.** {F16103
28fc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
28fd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
28fe0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
28ff0 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a  haves exactly.**
29000 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b            like [
29010 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29020 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76  unction()] in ev
29030 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74  ery way except t
29040 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20  hat it.**       
29050 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68     interprets th
29060 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20  e zFunctionName 
29070 61 72 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20  argument as.**  
29080 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
29090 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
290a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
290b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 61   instead of as a
290c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
290d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
290e0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  -8..**.** {F1610
290f0 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
29100 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
29110 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
29120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29130 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
29140 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
29150 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
29160 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
29170 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
29180 6f 6e 73 20 69 6e 20 5b 64 61 74 61 62 61 73 65  ons in [database
29190 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
291a0 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
291b0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
291c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
291d0 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
291e0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
291f0 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
29200 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
29210 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
29220 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20  *.** {F16109} A 
29230 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
29240 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
29250 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
29260 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
29270 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63            replac
29280 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20  es the P, F, S, 
29290 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f  and L values fro
292a0 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  m any prior call
292b0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
292c0 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58     the same D, X
292d0 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65  , N, and E value
292e0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32  s..**.** {F16112
292f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29300 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
29310 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,X,...)] interfa
29320 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a  ce fails with.**
29330 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
29340 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
29350 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65  TE_ERROR] if the
29360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
29370 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20  me X is.**      
29380 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20      longer than 
29390 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73  255 bytes exclus
293a0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20  ive of the zero 
293b0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
293c0 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65  * {F16118} Eithe
293d0 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c  r F must be NULL
293e0 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
293f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73   non-NULL or els
29400 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e F.**          
29410 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
29420 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
29430 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20  , otherwise.**  
29440 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
29450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29460 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
29470 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
29480 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a  TE_ERROR]..**.**
29490 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {F16121} The [s
294a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
294b0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
294c0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
294d0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
294e0 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
294f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
29500 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70  f there exist [p
29510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29520 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts].**          
29530 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29540 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
29550 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
29560 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20  ** {F16124} The 
29570 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29580 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
29590 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
295a0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
295b0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
295c0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
295d0 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74  RROR] if paramet
295e0 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67  er N (specifying
295f0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
29600 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d          of argum
29610 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
29620 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72  function being r
29630 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65  egistered) is le
29640 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
29650 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
29660 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
29670 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20  * {F16127} When 
29680 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
29690 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
296a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
296b0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
296c0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
296d0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
296e0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
296f0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
29700 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
29710 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
29720 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
29730 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
29740 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
29750 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
29760 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  y N..**.** {F161
29770 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
29780 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
29790 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
297a0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
297b0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
297c0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
297d0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
297e0 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63  for the SQL func
297f0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
29800 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
29810 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
29820 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
29830 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6133} When calls
29840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
29850 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
29860 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
29870 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
29880 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
29890 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
298a0 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  e function X.** 
298b0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
298c0 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n one implementa
298d0 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e  tion has N>=0 an
298e0 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20  d the other has 
298f0 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20  N=(-1).**       
29900 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74     the implement
29910 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
29920 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65  -zero N is prefe
29930 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
29940 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
29950 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
29960 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
29970 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
29980 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
29990 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
299a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
299b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
299c0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
299d0 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
299e0 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
299f0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
29a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
29a10 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
29a20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
29a30 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
29a40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29a50 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
29a60 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64  ing is preferred
29a70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d  ..**.** {F16139}
29a80 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
29a90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
29aa0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
29ab0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
29ac0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29ad0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
29ae0 4c 29 5d 20 74 68 65 20 66 69 6e 69 61 6c 69 7a  L)] the finializ
29af0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
29b00 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61  unction L will a
29b10 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
29b20 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
29b30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29b40 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
29b50 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
29b60 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
29b70 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65  .** {F16142} Whe
29b80 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
29b90 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
29ba0 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
29bb0 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
29bc0 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
29bd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29be0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
29bf0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
29c00 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
29c10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29c20 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
29c30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29c40 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
29c50 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
29c60 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
29c70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
29c80 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
29c90 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
29ca0 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77  arameter are alw
29cb0 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ays [protected s
29cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29cd0 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  jects..*/.int sq
29ce0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29cf0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
29d00 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
29d10 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
29d20 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
29d30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
29d40 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
29d50 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
29d60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
29d70 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
29d80 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
29d90 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
29da0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
29db0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
29dc0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
29dd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
29de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
29df0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
29e00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
29e10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
29e20 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
29e30 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
29e40 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
29e50 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
29e60 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
29e70 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
29e80 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
29e90 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
29ea0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
29eb0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
29ec0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
29ed0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
29ee0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
29ef0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
29f00 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36  Encodings {F1026
29f10 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  7}.**.** These c
29f20 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
29f30 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
29f40 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
29f50 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
29f60 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
29f70 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
29f80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
29f90 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
29fa0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29fb0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
29fc0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
29fd0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
29fe0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
29ff0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2a000 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2a010 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2a020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a030 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2a040 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2a050 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2a060 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2a070 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2a080 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2a090 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a0a0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2a0b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2a0c0 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
2a0d0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
2a0e0 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
2a0f0 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
2a100 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2a110 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2a120 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2a130 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2a140 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
2a150 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
2a160 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
2a170 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
2a180 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
2a190 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2a1a0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2a1b0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2a1c0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2a1d0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2a1e0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2a1f0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2a200 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2a210 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
2a220 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a230 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2a240 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a250 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2a260 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2a270 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2a280 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2a290 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2a2a0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2a2b0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2a2c0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2a2d0 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
2a2e0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2a2f0 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  up(void);.int sq
2a300 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2a310 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2a320 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2a330 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2a340 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
2a350 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2a360 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2a370 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2a380 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a  es {F15100}.**.*
2a390 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
2a3a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a3b0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
2a3c0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
2a3d0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
2a3e0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
2a3f0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
2a400 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
2a410 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
2a420 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2a430 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
2a440 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
2a450 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
2a460 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
2a470 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
2a480 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
2a490 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a4a0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2a4b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a4c0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
2a4d0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
2a4e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2a4f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2a500 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
2a510 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2a520 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
2a530 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
2a540 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
2a550 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
2a560 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a570 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
2a580 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
2a590 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
2a5a0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
2a5b0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2a5c0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
2a5d0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
2a5e0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
2a5f0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
2a600 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a610 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
2a620 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
2a630 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
2a640 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a650 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
2a660 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
2a670 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2a680 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
2a690 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a6a0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
2a6b0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
2a6c0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
2a6d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2a6e0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
2a6f0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2a700 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  g .** [sqlite3_c
2a710 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c  olumn_blob | sql
2a720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f  ite3_column_* ro
2a730 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74  utines] except t
2a740 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f  hat .** these ro
2a750 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2a760 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2a770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a780 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 0a 2a 2a  bject pointer.**
2a790 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2a7a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2a7b0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2a7c0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2a7d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2a7e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a7f0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2a800 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
2a810 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2a820 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2a830 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2a840 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
2a850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a860 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2a870 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a880 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2a890 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
2a8a0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2a8b0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2a8c0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2a8d0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
2a8e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2a8f0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2a900 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2a910 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2a920 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2a930 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2a940 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2a950 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2a960 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2a970 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2a980 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2a990 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2a9a0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2a9b0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2a9c0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2a9d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2a9e0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  ther.** words if
2a9f0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2aa00 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2aa10 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2aa20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2aa30 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e  version is done.
2aa40 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
2aa50 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2aa60 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  .  The .** [SQLI
2aa70 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2aa80 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2aa90 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2aaa0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
2aab0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
2aac0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
2aad0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
2aae0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
2aaf0 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  is returned from
2ab00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ab10 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2ab20 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2ab30 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2ab40 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2ab50 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2ab60 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2ab70 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2ab80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2ab90 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2aba0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2abb0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2abc0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2abd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2abe0 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  ext16()].  .**.*
2abf0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2ac00 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2ac10 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2ac20 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2ac30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2ac40 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2ac50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2ac60 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
2ac70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2ac80 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54  **.** {F15103} T
2ac90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2aca0 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2acb0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2acc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2acd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ace0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2acf0 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64   into a blob and
2ad00 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
2ad10 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2ad20 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2ad30 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2ad40 2a 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b  * {F15106} The [
2ad50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2ad60 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2ad70 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2ad80 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2ad90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2ada0 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20   blob or string 
2adb0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2adc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2add0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2ade0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2adf0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2ae00 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2ae10 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2ae20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2ae30 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2ae40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ae50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ae60 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
2ae70 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2ae80 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2ae90 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2aea0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2aeb0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2aec0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2aed0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2aee0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2aef0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2af00 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2af10 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2af20 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2af30 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2af40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2af50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2af60 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2af70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2af80 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2af90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2afa0 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2afb0 0a 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65  .** {F15112} The
2afc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2afd0 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2afe0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2aff0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2b000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b010 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2b020 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2b030 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2b040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2b050 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2b060 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2b070 20 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {F15115} The [s
2b080 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2b090 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2b0a0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2b0b0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2b0c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b0d0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2b0e0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2b0f0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2b100 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2b110 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2b120 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2b130 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38  r..**.** {F15118
2b140 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2b150 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2b160 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2b170 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2b180 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2b190 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b1a0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2b1b0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2b1c0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2b1d0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2b1e0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2b1f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d  ..**.** {F15121}
2b200 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2b210 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2b220 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2b230 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2b240 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2b250 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2b260 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2b270 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2b280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2b290 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2b2a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2b2b0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2b2c0 7b 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71  {F15124} The [sq
2b2d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2b2e0 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  16(V)] interface
2b2f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2b300 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2b310 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b320 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2b330 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2b340 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2b350 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2b360 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2b370 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
2b380 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2b390 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b3a0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2b3b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20  .**.** {F15127} 
2b3c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2b3d0 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20  ue_text16be(V)] 
2b3e0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2b3f0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2b400 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2b410 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b420 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2b430 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2b440 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2b450 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62  aligned UTF-16 b
2b460 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
2b470 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2b480 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b490 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2b4a0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30  g..**.** {F15130
2b4b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2b4c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
2b4d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2b4e0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2b4f0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2b500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b510 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2b520 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2b530 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2b540 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2b550 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
2b560 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2b570 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2b580 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2b590 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
2b5a0 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  15133} The [sqli
2b5b0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56  te3_value_type(V
2b5c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2b5d0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
2b5e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b5f0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
2b600 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2b610 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
2b620 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
2b630 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
2b640 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2b650 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
2b660 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2b670 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2b680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d  ..**.** {F15136}
2b690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2b6a0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2b6b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2b6c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20  onverts.**      
2b6d0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
2b6e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b6f0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2b700 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65  either an intege
2b710 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  r or.**         
2b720 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2b730 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61  t value if it ca
2b740 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20  n do so without 
2b750 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  loss of.**      
2b760 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c      information,
2b770 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65   and returns one
2b780 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
2b790 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2b7a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2b7b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2b7c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2b7d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2b7e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2b7f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2b800 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2b810 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2b820 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2b830 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e   V after the con
2b840 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e  version attempt.
2b850 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2b860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2b870 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
2b880 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2b890 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
2b8a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2b8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2b8c0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
2b8d0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
2b8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
2b8f0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
2b900 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2b910 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
2b920 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
2b930 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2b940 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
2b950 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2b960 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2b970 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
2b980 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
2b990 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2b9a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2b9b0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
2b9c0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2b9d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2b9e0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
2b9f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2ba00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ba10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2ba20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2ba30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2ba40 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
2ba50 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2ba60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2ba70 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
2ba80 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
2ba90 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2baa0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
2bab0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31  tion Context {F1
2bac0 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6210}.**.** The 
2bad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2bae0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2baf0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2bb00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
2bb10 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
2bb20 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
2bb30 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20  g their state.  
2bb40 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
2bb50 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2bb60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2bb70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
2bb80 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2bb90 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2bba0 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
2bbb0 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
2bbc0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f  f memory.** zero
2bbd0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  s that memory, a
2bbe0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2bbf0 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f  nter to it..** O
2bc00 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2bc10 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2bc20 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2bc30 74 65 5f 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20  te_context().** 
2bc40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2bc50 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2bc60 69 6e 64 65 78 2c 20 74 68 65 20 73 61 6d 65 20  index, the same 
2bc70 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2bc80 65 64 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ed..** The imple
2bc90 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
2bca0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
2bcb0 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e  n use the return
2bcc0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
2bcd0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
2bce0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
2bcf0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2bd00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
2bd10 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
2bd20 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
2bd30 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2bd40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2bd50 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2bd60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
2bd70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2bd80 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
2bd90 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
2bda0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
2bdb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bdc0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
2bdd0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2bde0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2bdf0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
2be00 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2be10 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2be20 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2be30 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2be40 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
2be50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2be60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2be70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2be80 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74  16211} The first
2be90 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
2bea0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2beb0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2bec0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2bed0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
2bee0 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72  tance of an aggr
2bef0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28  egate function (
2bf00 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2bf10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2bf20 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53  text C) causes S
2bf30 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74  QLite to allocat
2bf40 69 6f 6e 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ion N bytes of m
2bf50 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20  emory,.**       
2bf60 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d     zero that mem
2bf70 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  ory, and return 
2bf80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2bf90 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20   allocated.**   
2bfa0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a         memory..*
2bfb0 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66  *.** {F16213} If
2bfc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2bfd0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2bfe0 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
2bff0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
2c000 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2c010 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
2c020 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2c030 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35  0..**.** {F16215
2c040 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
2c050 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2c060 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
2c070 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2c080 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2c090 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
2c0a0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
2c0b0 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
2c0c0 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
2c0d0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
2c0e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c0f0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
2c100 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
2c110 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
2c120 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2c130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ion..**.** {F162
2c140 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
2c150 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
2c160 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2c170 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
2c180 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2c190 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2c1a0 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
2c1b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2c1c0 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
2c1d0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
2c1e0 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
2c1f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c200 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
2c210 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
2c220 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2c230 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2c240 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
2c250 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2c260 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2c270 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2c280 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
2c290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c2a0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
2c2b0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
2c2c0 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
2c2d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2c2e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c2f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2c300 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2c310 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2c320 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2c330 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2c340 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2c350 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c360 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2c370 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c380 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2c390 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2c3a0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2c3b0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2c3c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2c3d0 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
2c3e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2c3f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2c400 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2c410 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2c420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c430 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c440 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2c450 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c460 0a 2a 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65  .** {F16243} The
2c470 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2c480 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
2c490 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2c4a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2c4b0 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
2c4c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2c4d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c4e0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2c4f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2c500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c510 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2c520 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
2c530 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
2c540 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
2c550 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c560 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2c580 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
2c590 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2c5a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
2c5b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2c5c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c5d0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2c5e0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
2c5f0 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a  ns {F16250}.**.*
2c600 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
2c610 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2c620 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c630 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2c640 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2c650 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c660 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2c670 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2c680 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2c690 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c6a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2c6b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c6c0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2c6d0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2c6e0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2c6f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2c700 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c710 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2c720 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35  TS:.**.** {F1625
2c730 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2c740 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2c750 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(C)] interface 
2c760 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2c770 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2c780 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    D pointer from
2c790 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2c7a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c7b0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2c7c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2c7d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c7e0 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2c7f0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2c800 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2c810 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2c820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2c830 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
2c840 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2c850 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2c860 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2c870 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2c880 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2c890 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2c8a0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2c8b0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2c8c0 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a  a {F16270}.**.**
2c8d0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2c8e0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2c8f0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2c900 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2c910 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2c920 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20   meta-data with 
2c930 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
2c940 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
2c950 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
2c960 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
2c970 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2c980 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
2c990 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
2c9a0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
2c9b0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
2c9c0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
2c9d0 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61  ted meta-data ma
2c9e0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2c9f0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2ca00 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2ca10 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2ca20 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2ca30 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2ca40 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2ca50 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2ca60 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2ca70 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2ca80 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64  red as.** meta-d
2ca90 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2caa0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2cab0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2cac0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2cad0 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2cae0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2caf0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2cb00 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2cb10 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2cb20 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2cb30 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2cb40 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2cb50 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2cb60 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2cb70 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2cb80 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2cb90 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
2cba0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2cbb0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2cbc0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2cbd0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d  ter to the meta-
2cbe0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2cbf0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2cc00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2cc10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2cc20 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2cc30 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2cc40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cc50 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ed function..** 
2cc60 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20  If no meta-data 
2cc70 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62 65  has been ever be
2cc80 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
2cc90 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
2cca0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
2ccb0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
2ccc0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2ccd0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68 61   parameter.** ha
2cce0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
2ccf0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
2cd00 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c 69  s set, then sqli
2cd10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2cd20 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  ).** returns a N
2cd30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2cd40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2cd50 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2cd60 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2cd70 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70 6f   meta-data.** po
2cd80 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2cd90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2cda0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 66   the meta-data f
2cdb0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2cdc0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2cdd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cde0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2cdf0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2ce00 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2ce10 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2ce20 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2ce30 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2ce40 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2ce50 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69 73  ed. .** If it is
2ce60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2ce70 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2ce80 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a 2a  e destructor .**
2ce90 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2cea0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2ceb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2cec0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2ced0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61 74  .** the meta-dat
2cee0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
2cef0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
2cf00 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
2cf10 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
2cf20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2cf30 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
2cf40 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
2cf50 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
2cf60 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
2cf70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
2cf80 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61 74  nd drop meta-dat
2cf90 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72 61  a on.** any para
2cfa0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
2cfb0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
2cfc0 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
2cfd0 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68 61  rantee.** is tha
2cfe0 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  t the destructor
2cff0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
2d000 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
2d010 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70 65  ata is.** droppe
2d020 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
2d030 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20  tice, meta-data 
2d040 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
2d050 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
2d060 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
2d070 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2d080 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
2d090 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
2d0a0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
2d0b0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
2d0c0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
2d0d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d0e0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2d0f0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2d100 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2d110 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2d120 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2d130 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2d140 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20  .**.** {F16272} 
2d150 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
2d160 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69  _auxdata(C,N)] i
2d170 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d180 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
2d190 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61         to metada
2d1a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2d1b0 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  th the Nth param
2d1c0 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
2d1d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2d1e0 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65       whose conte
2d1f0 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c  xt is C, or NULL
2d200 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
2d210 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2d220 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2d230 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65  with that parame
2d240 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ter..**.** {F162
2d250 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  74} The [sqlite3
2d260 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
2d270 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,P,D)] interface
2d280 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64   assigns a metad
2d290 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
2d2a0 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65  pointer P to the
2d2b0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2d2c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2d2d0 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 0a  on with context.
2d2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a  **          C..*
2d2f0 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53 51  *.** {F16276} SQ
2d300 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2d310 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2d320 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20  D with a single 
2d330 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
2d340 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74 68       which is th
2d350 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74  e metadata point
2d360 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  er P following a
2d370 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20   call to.**     
2d380 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
2d390 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2d3a0 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20  D)] when SQLite 
2d3b0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a  ceases to hold.*
2d3c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d  *          the m
2d3d0 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b  etadata..**.** {
2d3e0 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63  F16277} SQLite c
2d3f0 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65  eases to hold me
2d400 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51  tadata for an SQ
2d410 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  L function param
2d420 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
2d430 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   when the value 
2d440 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  of that paramete
2d450 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  r changes..**.**
2d460 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20 5b   {F16278} When [
2d470 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2d480 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73  ata(C,N,P,D)] is
2d490 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65   invoked, the de
2d4a0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20  structor.**     
2d4b0 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66       is called f
2d4c0 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74  or any prior met
2d4d0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2d4e0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2d4f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2d500 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e      context C an
2d510 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a  d parameter N..*
2d520 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53 51  *.** {F16279} SQ
2d530 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64  Lite will call d
2d540 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61  estructors for a
2d550 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20 69  ny metadata it i
2d560 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20  s holding.**    
2d570 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74 69        in a parti
2d580 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20  cular [prepared 
2d590 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65  statement] S whe
2d5a0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  n either.**     
2d5b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d5c0 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69  set(S)] or [sqli
2d5d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
2d5e0 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76   is called..*/.v
2d5f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
2d600 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2d610 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2d620 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d630 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
2d640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2d650 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
2d660 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
2d670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d680 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
2d690 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
2d6a0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b  uctor Behavior {
2d6b0 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10280}.**.** Th
2d6c0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2d6d0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65  value for the de
2d6e0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2d6f0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2d700 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2d710 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2d720 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2d730 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
2d740 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2d750 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2d760 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2d770 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2d780 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2d790 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2d7a0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2d7b0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2d7c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2d7d0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a  estroyed.  The .
2d7e0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2d7f0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2d800 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2d810 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2d820 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2d830 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2d840 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2d850 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2d860 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2d870 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2d880 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2d890 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2d8a0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2d8b0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2d8c0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2d8d0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2d8e0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2d8f0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2d900 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2d910 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2d920 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2d930 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2d940 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2d950 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2d960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d970 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2d980 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2d990 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2d9a0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2d9b0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2d9c0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2d9d0 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F16400}.**.** 
2d9e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d9f0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
2da00 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
2da10 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
2da20 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
2da30 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2da40 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
2da50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2da60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2da70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2da80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2da90 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
2daa0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2dab0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2dac0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
2dad0 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
2dae0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2daf0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2db00 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
2db10 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
2db20 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
2db30 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
2db40 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
2db50 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
2db60 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
2db70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2db80 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2db90 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
2dba0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
2dbb0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2dbc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2dbd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
2dbe0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2dbf0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2dc00 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2dc10 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2dc20 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
2dc30 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
2dc40 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
2dc50 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
2dc60 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
2dc70 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
2dc80 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
2dc90 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
2dca0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71 6c  ter. .** The sql
2dcb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2dcc0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2dcd0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2dce0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2dcf0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2dd00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2dd10 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2dd20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2dd30 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2dd40 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2dd50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2dd60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2dd70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2dd80 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2dd90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2dda0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2ddb0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2ddc0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2ddd0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2dde0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ddf0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2de00 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2de10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2de20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2de30 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2de40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2de50 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2de60 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2de70 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2de80 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2de90 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
2dea0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2deb0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2dec0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2ded0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2dee0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2def0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2df00 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2df10 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2df20 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2df30 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
2df40 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2df50 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2df60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2df70 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2df80 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
2df90 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2dfa0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2dfb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2dfc0 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
2dfd0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
2dfe0 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
2dff0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2e000 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2e010 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2e020 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2e030 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2e040 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2e050 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2e060 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2e070 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2e080 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2e090 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2e0a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2e0b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2e0c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2e0d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2e0e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2e0f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2e100 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2e110 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2e120 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2e130 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2e140 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2e150 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2e160 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2e170 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2e180 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2e190 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2e1a0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
2e1b0 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
2e1c0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2e1d0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2e1e0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2e1f0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2e200 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2e210 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2e220 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2e230 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2e240 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2e250 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
2e260 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2e270 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2e280 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2e290 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2e2a0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2e2b0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2e2c0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2e2d0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
2e2e0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
2e2f0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
2e300 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
2e310 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2e320 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2e330 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2e340 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2e350 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2e360 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2e370 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
2e380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2e390 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
2e3a0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a  e causes SQLite.
2e3b0 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  ** to throw an e
2e3c0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
2e3d0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
2e3e0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
2e3f0 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74  .** to represent
2e400 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  .  The sqlite3_r
2e410 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2e420 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65  terface.** cause
2e430 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2e440 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  w an exception i
2e450 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2e460 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  he a.** memory a
2e470 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2e480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2e490 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2e4a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2e4b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2e4c0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2e4d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e4e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2e4f0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2e500 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2e510 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2e520 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
2e530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2e540 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2e550 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2e560 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2e570 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2e580 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2e590 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2e5a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2e5b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2e5c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2e5d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2e5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2e5f0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2e600 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2e610 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2e620 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e630 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2e640 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
2e650 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e660 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2e670 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2e680 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  , .** sqlite3_re
2e690 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2e6a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2e6b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2e6c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2e6d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2e6e0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2e6f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2e700 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2e710 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2e720 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2e730 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2e740 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2e750 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2e760 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2e770 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2e780 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2e790 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b  y..** SQLite tak
2e7a0 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2e7b0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2e7c0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2e7d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2e7e0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2e7f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2e800 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20  terfaces..** If 
2e810 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2e820 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2e830 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2e840 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2e850 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
2e860 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
2e870 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
2e880 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a  2nd parameter .*
2e890 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2e8a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2e8b0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
2e8c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2e8d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2e8e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2e8f0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
2e900 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
2e910 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
2e920 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
2e930 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
2e940 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
2e950 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
2e960 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
2e970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
2e980 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
2e990 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2e9a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2e9b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e9c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2e9d0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2e9e0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2e9f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2ea00 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2ea10 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2ea20 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2ea30 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2ea40 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2ea50 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2ea60 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2ea70 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2ea80 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2ea90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2eaa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2eab0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2eac0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2ead0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2eae0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2eaf0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2eb00 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73  en.** SQLite ass
2eb10 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2eb20 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c  xt or blob resul
2eb30 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70  t is constant sp
2eb40 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20  ace and.** does 
2eb50 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61  not copy the spa
2eb60 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  ce or call a des
2eb70 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
2eb80 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2eb90 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2eba0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2ebb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2ebc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ebd0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2ebe0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2ebf0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2ec00 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2ec10 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2ec20 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2ec30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2ec40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2ec50 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2ec60 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2ec70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2ec80 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2ec90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
2eca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2ecb0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2ecc0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2ecd0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2ece0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ecf0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2ed00 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2ed10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ed20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2ed30 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2ed40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2ed50 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2ed60 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2ed70 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2ed80 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2ed90 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2eda0 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  o that [sqlite3_
2edb0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2edc0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2edd0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2ede0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2edf0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2ee00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2ee10 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2ee20 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
2ee30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ee40 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2ee50 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2ee60 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2ee70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ee80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2ee90 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2eea0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2eeb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2eec0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2eed0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2eee0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2eef0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2ef00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2ef10 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2ef20 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74  ent thread .** t
2ef30 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
2ef40 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
2ef50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ef60 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
2ef70 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
2ef80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
2ef90 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
2efa0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2efb0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
2efc0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  NTS:.**.** {F164
2efd0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
2efe0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2eff0 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
2f000 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
2f010 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b  * {F16406} The [
2f020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2f030 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
2f040 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2f050 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f060 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2f070 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2f080 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20   a blob that is 
2f090 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
2f0a0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
2f0b0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
2f0c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
2f0d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
2f0e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2f0f0 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
2f100 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2f110 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2f120 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2f130 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2f140 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
2f150 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
2f160 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68  *.** {F16412} Th
2f170 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2f180 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
2f190 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2f1a0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
2f1b0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
2f1c0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2f1d0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2f1e0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2f1f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2f200 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
2f210 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73   UTF8 error mess
2f220 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
2f230 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
2f240 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
2f250 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
2f260 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
2f270 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
2f280 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
2f290 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2f2a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
2f2b0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
2f2c0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2f2d0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2f2e0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2f2f0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
2f300 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
2f310 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
2f320 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
2f330 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61  ] and a UTF16 na
2f340 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2f350 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
2f360 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
2f370 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
2f380 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2f390 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
2f3a0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
2f3b0 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
2f3c0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
2f3d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54  **.** {F16418} T
2f3e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2f3f0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2f400 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2f410 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2f420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2f430 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
2f440 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2f450 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2f460 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2f470 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
2f480 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
2f490 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
2f4a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
2f4b0 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
2f4c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2f4d0 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
2f4e0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2f4f0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2f500 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2f510 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2f520 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2f530 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2f540 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2f550 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
2f560 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
2f570 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2f580 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {F16424} The [sq
2f590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f5a0 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
2f5b0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2f5c0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2f5d0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2f5e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2f5f0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2f600 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2f610 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
2f620 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
2f630 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
2f640 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nged..**.** {F16
2f650 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
2f660 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
2f670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2f680 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2f690 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2f6a0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2f6b0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2f6c0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
2f6d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d  ..**.** {F16430}
2f6e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2f6f0 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
2f700 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2f710 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2f720 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2f730 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2f740 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
2f750 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
2f760 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54  **.** {F16433} T
2f770 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2f780 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
2f790 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2f7a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2f7b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2f7c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
2f7d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2f7e0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2f7f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2f800 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2f810 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2f820 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2f830 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2f840 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2f850 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  F8 string.**    
2f860 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68        V up to th
2f870 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2f880 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
2f890 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
2f8a0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
2f8b0 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
2f8c0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
2f8d0 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {F16439} The [sq
2f8e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f8f0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
2f900 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2f910 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f920 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2f930 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2f940 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69 76   the UTF16 nativ
2f950 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2f960 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2f970 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2f980 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2f990 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2f9a0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2f9b0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2f9c0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2f9d0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2f9e0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2f9f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2fa00 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2fa10 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2fa20 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2fa30 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2fa40 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2fa50 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69 61   UTF16 big-endia
2fa60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2fa70 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2fa80 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2fa90 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2faa0 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74  is negative or t
2fab0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
2fac0 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
2fad0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
2fae0 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20 5b  * {F16445} The [
2faf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fb00 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
2fb10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2fb20 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2fb30 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2fb40 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2fb50 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6c  o be the UTF16 l
2fb60 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
2fb70 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2fb80 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2fb90 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2fba0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2fbb0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2fbc0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2fbd0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2fbe0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2fbf0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2fc00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
2fc10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2fc20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2fc30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2fc40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2fc50 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63 74  to be [unprotect
2fc60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fc70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
2fc80 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
2fc90 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
2fca0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2fcb0 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
2fcc0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2fcd0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2fce0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2fcf0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2fd00 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20 61  N-byte blob of a
2fd10 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
2fd20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {F16454} The [sq
2fd30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fd40 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
2fd50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2fd60 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
2fd70 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
2fd80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
2fd90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2fda0 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
2fdb0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2fdc0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ing..**.** {F164
2fdd0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
2fde0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
2fdf0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
2fe00 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
2fe10 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2fe20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2fe30 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
2fe40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2fe50 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
2fe60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2fe70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fe80 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
2fe90 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2fea0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2feb0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
2fec0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
2fed0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
2fee0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
2fef0 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
2ff00 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
2ff10 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
2ff20 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
2ff30 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
2ff40 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
2ff50 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  utable..**.** {F
2ff60 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
2ff70 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
2ff80 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2ff90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2ffa0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2ffb0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2ffc0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
2ffd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
2ffe0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
2fff0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
30000 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
30010 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
30020 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
30030 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
30040 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
30050 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
30060 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
30070 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
30080 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
30090 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
300a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
300b0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
300c0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
300d0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
300e0 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20  .** {F16463} If 
300f0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
30100 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30120 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
30130 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30140 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
30150 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
30160 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30170 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
30180 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
30190 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
301a0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
301b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
301c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
301d0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
301e0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
301f0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
30200 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
30210 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
30220 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
30230 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a  NSIENT] then .**
30240 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
30250 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
30260 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
30270 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
30280 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
30290 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
302a0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
302b0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
302c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
302d0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
302e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
302f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30300 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
30310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30320 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
30330 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
30340 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
30350 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
30360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30370 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
30380 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30390 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
303a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
303b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
303c0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
303d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
303e0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
303f0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
30400 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30410 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
30420 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
30430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30440 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
30450 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
30460 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
30470 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
30480 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
30490 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
304a0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
304b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
304c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
304d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
304e0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
304f0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
30500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30510 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
30520 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
30530 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30540 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
30550 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30560 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
30570 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
30580 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30590 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
305a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
305b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
305c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
305d0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
305e0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
305f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30600 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
30610 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
30620 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
30630 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
30640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
30650 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
30660 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
30670 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
30680 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
30690 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
306a0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
306b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
306c0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
306d0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
306e0 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
306f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
30700 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
30710 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
30720 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
30730 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
30740 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
30750 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
30760 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  . .**.** The nam
30770 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
30780 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
30790 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
307a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
307b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
307c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
307d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
307e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
307f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
30800 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
30810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30820 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
30830 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
30840 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
30850 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
30860 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
30870 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
30880 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
30890 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
308a0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
308b0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
308c0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
308d0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
308e0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
308f0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
30900 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
30910 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
30920 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
30930 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
30940 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
30950 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
30960 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
30970 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
30980 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
30990 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
309a0 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
309b0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
309c0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
309d0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
309e0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
309f0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
30a00 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
30a10 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68 65   of UTF16 in the
30a20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
30a30 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
30a40 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
30a50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
30a60 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
30a70 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
30a80 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
30a90 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
30aa0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
30ab0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
30ac0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
30ad0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
30ae0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
30af0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
30b00 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
30b10 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
30b20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73  application.** s
30b30 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
30b40 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
30b50 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
30b60 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
30b70 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66  ssed as.** the f
30b80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
30b90 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30ba0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a  _collation() or.
30bb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
30bc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
30bd0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
30be0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
30bf0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
30c00 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
30c10 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
30c20 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
30c30 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
30c40 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
30c50 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
30c60 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
30c70 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
30c80 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
30c90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
30ca0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
30cb0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
30cc0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
30cd0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
30ce0 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  } The applicatio
30cf0 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
30d00 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
30d10 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
30d20 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
30d30 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
30d40 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
30d50 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
30d60 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
30d70 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
30d80 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
30d90 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
30da0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
30db0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30dc0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
30dd0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
30de0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30df0 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
30e00 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
30e10 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
30e20 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
30e30 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
30e40 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
30e50 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
30e60 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
30e70 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
30e80 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
30e90 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
30ea0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
30eb0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
30ec0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
30ed0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30ee0 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43  ation_v2()..** C
30ef0 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
30f00 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20  stroyed when.** 
30f10 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
30f20 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
30f30 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
30f40 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
30f50 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65  ctions.** or whe
30f60 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  n the [sqlite3*]
30f70 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
30f80 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
30f90 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
30fa0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
30fb0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
30fc0 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  603} A successfu
30fd0 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  l call to the.**
30fe0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30ff0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31000 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
31010 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  ,D)] interface.*
31020 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
31030 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20  ters function F 
31040 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  as the compariso
31050 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20  n function used 
31060 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
31070 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69  mplement collati
31080 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61 73  on X on [databas
31090 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
310a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
310b0 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
310c0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
310d0 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
310e0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
310f0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
31100 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
31110 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31120 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
31130 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
31140 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
31150 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
31160 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
31170 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
31180 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
31190 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
311a0 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
311b0 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
311c0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
311d0 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
311e0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
311f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31200 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
31210 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
31220 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
31230 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
31240 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
31250 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
31260 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
31270 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
31280 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54  **.** {F16609} T
31290 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
312a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
312b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
312c0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
312d0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
312e0 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
312f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
31300 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
31310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
31320 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31330 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
31340 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  Lite..**.** {F16
31350 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
31360 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
31370 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
31380 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
31390 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {F16615} A col
313a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
313b0 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
313c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
313d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
313e0 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
313f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
31400 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  se()]..**.** {F1
31410 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
31420 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
31430 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31440 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
31450 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
31460 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
31470 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
31480 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
31490 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
314a0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
314b0 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
314c0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
314d0 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  f F..**.** {F166
314e0 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
314f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31500 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
31510 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
31520 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
31530 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
31540 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31550 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
31560 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
31570 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
31580 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
31590 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
315a0 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {F16624} Foll
315b0 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
315c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
315d0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
315e0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
315f0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
31600 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
31610 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
31620 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
31630 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
31640 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ions on [databas
31650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
31660 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
31670 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
31680 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
31690 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  g sequence name 
316a0 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37  X..**.** {F16627
316b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
316c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
316d0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
316e0 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
316f0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
31700 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31710 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
31720 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
31730 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
31740 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
31750 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
31760 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
31770 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
31780 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
31790 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
317a0 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {F16630} When mu
317b0 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
317c0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
317d0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
317e0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
317f0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
31800 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
31810 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
31820 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
31830 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
31840 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
31850 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
31860 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
31870 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
31880 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
31890 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
318a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
318b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
318c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
318d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
318e0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
318f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
31900 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
31910 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
31920 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
31930 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
31940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31950 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
31960 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
31970 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
31980 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
31990 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
319a0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
319b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
319c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
319d0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
319e0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
319f0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31a00 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
31a10 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
31a20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31a30 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31a40 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
31a50 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
31a60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
31a70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
31a80 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
31a90 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
31aa0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
31ab0 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16700}.**.**
31ac0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
31ad0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
31ae0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
31af0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
31b00 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
31b10 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
31b20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
31b30 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
31b40 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
31b50 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
31b60 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
31b70 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
31b80 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
31b90 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75  uence is.** requ
31ba0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
31bb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
31bc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
31bd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
31be0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
31bf0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
31c00 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
31c10 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
31c20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31c30 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
31c40 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
31c50 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20  -8. {F16703} If 
31c60 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
31c70 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
31c80 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a  used, the names.
31c90 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73  ** are passed as
31ca0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
31cb0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
31cc0 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20  rder. A call to 
31cd0 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69  either.** functi
31ce0 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20  on replaces any 
31cf0 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63  existing callbac
31d00 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
31d10 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
31d20 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
31d30 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
31d40 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
31d50 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
31d60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
31d70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
31d80 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
31d90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
31da0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
31db0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
31dc0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  he database.** h
31dd0 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72  andle.  The thir
31de0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
31df0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
31e00 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
31e10 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
31e20 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
31e30 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
31e40 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
31e50 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
31e60 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
31e70 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
31e80 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
31e90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31ea0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
31eb0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
31ec0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
31ed0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
31ee0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
31ef0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
31f00 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
31f10 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
31f20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31f30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
31f40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
31f50 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31f60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31f70 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
31f80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
31f90 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73  .** {F16702} A s
31fa0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
31fb0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
31fc0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
31fd0 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
31fe0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
31ff0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
32000 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
32010 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
32020 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32030 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
32040 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
32050 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
32060 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
32070 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
32080 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
32090 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
320a0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
320b0 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
320c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
320d0 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   about..**.** {F
320e0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
320f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
32100 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32110 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
32120 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32130 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
32140 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
32150 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
32160 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
32170 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
32180 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
32190 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
321a0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
321b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
321c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
321d0 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {F16706} The nam
321e0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
321f0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
32200 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
32210 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32220 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
32230 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
32240 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
32250 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
32260 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
32270 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
32280 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
32290 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
322a0 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
322b0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
322c0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
322d0 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
322e0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
322f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
32300 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
32310 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a  d16()]..**.** .*
32320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
32330 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
32340 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
32350 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
32360 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
32370 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
32380 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
32390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
323a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
323b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
323c0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
323d0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
323e0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
323f0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
32400 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
32410 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
32420 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
32430 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
32440 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
32450 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
32460 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
32470 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
32480 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
32490 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
324a0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
324b0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
324c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
324d0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
324e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
324f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
32500 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
32510 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
32520 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
32530 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
32540 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
32550 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
32560 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
32570 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
32580 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
32590 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
325a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
325b0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
325c0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
325d0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
325e0 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
325f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
32600 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
32610 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
32620 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
32630 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
32640 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
32650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
32660 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
32670 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
32680 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
32690 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
326a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
326b0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
326c0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
326d0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
326e0 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
326f0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
32700 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31  A Short Time {F1
32710 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0530}.**.** The 
32720 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
32730 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73  function.** caus
32740 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
32750 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
32760 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
32770 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
32780 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
32790 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
327a0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
327b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
327c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
327d0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
327e0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
327f0 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  th .** milliseco
32800 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
32810 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
32820 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
32830 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20  d up to .** the 
32840 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
32850 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
32860 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
32870 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a  eep actually .**
32880 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
32890 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
328a0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
328b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
328c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
328d0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
328e0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
328f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
32900 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
32910 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
32920 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
32930 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d  :.**.** {F10533}
32940 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
32950 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
32960 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
32970 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
32980 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
32990 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
329a0 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
329b0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
329c0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
329d0 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
329e0 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
329f0 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
32a00 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
32a10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d  ..**.** {F10536}
32a20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
32a30 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
32a40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
32a50 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
32a60 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
32a70 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
32a80 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
32a90 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
32aa0 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
32ab0 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
32ac0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
32ad0 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
32ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
32af0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
32b00 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
32b10 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
32b20 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
32b30 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
32b40 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
32b50 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
32b60 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
32b70 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
32b80 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
32b90 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
32ba0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
32bb0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
32bc0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
32bd0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
32be0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
32bf0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
32c00 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
32c10 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  .** is NULL poin
32c20 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
32c30 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66   does a search f
32c40 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
32c50 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66  e temporary.** f
32c60 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
32c70 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
32c80 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
32c90 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
32ca0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
32cb0 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65  ection.** has be
32cc0 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
32cd0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
32ce0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
32cf0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
32d00 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
32d10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
32d20 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
32d30 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
32d40 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
32d50 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
32d60 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
32d70 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
32d80 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
32d90 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
32da0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
32db0 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
32dc0 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
32dd0 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75  atabase Is In Au
32de0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
32df0 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12930}.**.** Th
32e00 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
32e10 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
32e20 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
32e30 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
32e40 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
32e50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32e60 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
32e70 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
32e80 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
32e90 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ly.   Autocommit
32ea0 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62   mode is on.** b
32eb0 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f  y default.  Auto
32ec0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
32ed0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
32ee0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
32ef0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
32f00 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
32f10 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
32f20 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
32f30 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
32f40 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
32f50 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
32f60 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
32f70 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
32f80 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
32f90 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
32fa0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
32fb0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
32fc0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
32fd0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
32fe0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
32ff0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
33000 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
33010 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
33020 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
33030 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
33040 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
33050 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
33060 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
33070 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
33080 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
33090 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
330a0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
330b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
330c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31  S:.**.** {F12931
330d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
330e0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29  et_autocommit(D)
330f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
33100 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
33110 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
33120 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   if the [databas
33130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
33140 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
33150 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20  autocommit.**   
33160 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73         mode, res
33170 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
33180 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f   {F12932} Autoco
33190 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
331a0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
331b0 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63  * {F12933} Autoc
331c0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
331d0 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  sabled by a succ
331e0 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73  essful [BEGIN] s
331f0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
33200 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {F12934} Autocom
33210 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  mit mode is enab
33220 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
33230 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  ful [COMMIT] or 
33240 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20  [ROLLBACK].**   
33250 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
33260 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ..** .**.** LIMI
33270 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20  TATIONS:.***.** 
33280 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {U12936} If anot
33290 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
332a0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
332b0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
332c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
332d0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
332e0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
332f0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
33300 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
33310 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
33320 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
33330 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
33340 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
33350 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
33360 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
33370 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
33380 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
33390 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31   Statement {F131
333a0 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20}.**.** The sq
333b0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
333c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
333d0 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65  urns the [sqlite
333e0 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
333f0 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
33400 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33410 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
33420 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  ** The database 
33430 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20  handle returned 
33440 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
33450 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73  ndle.** is the s
33460 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
33470 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
33480 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33490 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
334a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
334b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
334c0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
334d0 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
334e0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
334f0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
33500 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
33510 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54  **.** {F13123} T
33520 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
33530 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
33540 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
33550 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
33560 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
33570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
33580 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
33590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
335a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
335b0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
335c0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
335d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
335e0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
335f0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
33600 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
33610 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
33620 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
33630 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
33640 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
33650 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
33660 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
33670 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
33680 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
33690 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
336a0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
336b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
336c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
336d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
336e0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
336f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
33700 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
33710 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
33720 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
33730 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
33740 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
33750 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
33760 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
33770 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
33780 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
33790 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
337a0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
337b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
337c0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
337d0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
337e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
337f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
33800 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
33810 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
33820 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
33830 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
33840 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  k.  If the callb
33850 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
33860 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  hook function .*
33870 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
33880 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ro, then the com
33890 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
338a0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
338b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
338c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
338d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
338e0 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
338f0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
33900 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
33910 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
33920 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  d..**.** Registe
33930 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
33940 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
33950 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
33960 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
33970 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
33980 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
33990 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
339a0 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  en .** rolled ba
339b0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
339c0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
339d0 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
339e0 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
339f0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
33a00 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
33a10 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
33a20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
33a30 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
33a40 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
33a50 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
33a60 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
33a70 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
33a80 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
33a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33aa0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
33ab0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
33ac0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
33ad0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
33ae0 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
33af0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
33b00 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
33b10 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
33b20 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
33b30 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
33b40 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  o>.**.** These a
33b50 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  re experimental 
33b60 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61  interfaces and a
33b70 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
33b80 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ange..**.** INVA
33b90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
33ba0 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
33bb0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
33bc0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
33bd0 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
33be0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
33bf0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
33c00 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
33c10 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
33c20 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
33c30 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
33c40 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74   commits on [dat
33c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33c60 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
33c70 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  52} The [sqlite3
33c80 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
33c90 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
33ca0 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
33cb0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
33cc0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
33cd0 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
33ce0 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20  e same .**      
33cf0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
33d00 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f  nnection ] D , o
33d10 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
33d20 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
33d30 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
33d40 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20  cular [database 
33d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
33d60 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
33d70 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
33d80 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
33d90 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
33da0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
33db0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
33dc0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
33dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
33de0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
33df0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
33e00 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
33e10 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
33e20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
33e30 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
33e40 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
33e50 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
33e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33e70 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
33e80 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
33e90 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
33ea0 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
33eb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
33ec0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
33ed0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
33ee0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
33ef0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
33f00 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
33f10 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
33f20 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
33f30 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
33f40 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
33f50 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
33f60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
33f70 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
33f80 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
33f90 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
33fa0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
33fb0 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64  rolls back on [d
33fc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33fd0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
33fe0 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
33ff0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
34000 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
34010 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
34020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
34030 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
34040 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
34050 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20  h the same .**  
34060 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
34070 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44  e connection ] D
34080 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68   , or NULL on th
34090 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
340a0 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
340b0 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62  articular [datab
340c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
340d0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33  D..**.** {F12963
340e0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
340f0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
34100 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
34110 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
34120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
34130 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
34140 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
34150 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20  12964} If the F 
34160 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
34170 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
34180 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
34190 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
341a0 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b  hen the rollback
341b0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
341c0 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
341d0 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
341e0 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
341f0 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
34200 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e  tion rolls back.
34210 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
34220 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
34230 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
34240 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
34250 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
34260 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
34270 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
34280 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
34290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
342a0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
342b0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
342c0 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a  s {F12970}.**.**
342d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
342e0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
342f0 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65 72  face.** register
34300 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
34310 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64  ction with the d
34320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34330 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  on identified by
34340 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61   the .** first a
34350 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e  rgument to be in
34360 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
34370 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
34380 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
34390 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
343a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
343b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
343c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f  this function fo
343d0 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64  r the same .** d
343e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
343f0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
34400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
34410 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
34420 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34430 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
34440 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f  ke when a .** ro
34450 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
34460 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
34470 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  d. .** The first
34480 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
34490 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
344a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
344b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
344c0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
344d0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
344e0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  cond callback .*
344f0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  * argument is on
34500 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
34510 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
34520 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
34530 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70  _UPDATE],.** dep
34540 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
34550 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
34560 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
34570 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
34580 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
34590 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75   .** fourth argu
345a0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
345b0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
345c0 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64 61  inters to the da
345d0 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74  tabase and .** t
345e0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
345f0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
34600 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69  d row..** The fi
34610 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
34620 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68  ameter is .** th
34630 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
34640 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
34650 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
34660 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
34670 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65  id after .** the
34680 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
34690 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
346a0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
346b0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
346c0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
346d0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
346e0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
346f0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
34700 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
34710 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
34720 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
34730 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
34740 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
34750 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
34760 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
34770 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
34780 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34790 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31  S:.**.** {F12971
347a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
347b0 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
347c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  )] interface cau
347d0 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ses callback.** 
347e0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
347f0 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
34800 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72  d with first par
34810 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
34820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
34830 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64  table row is mod
34840 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c  ified, inserted,
34850 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a   or deleted on.*
34860 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
34870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34880 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37   D..**.** {F1297
34890 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
348a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
348b0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
348c0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a  turns the value.
348d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
348e0 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75   for the previou
348f0 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61  s call on the sa
34900 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
34910 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20  nection] D,.**  
34920 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
34930 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63 61  for the first ca
34940 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  ll..**.** {F1297
34950 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74 65  5} If the update
34960 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46   hook callback F
34970 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64   in [sqlite3_upd
34980 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
34990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
349a0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f  NULL then the no
349b0 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b   update callback
349c0 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  s are made..**.*
349d0 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63 68 20  * {F12977} Each 
349e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
349f0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
34a00 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70  ,P)] overrides p
34a10 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  rior calls.**   
34a20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73 61         to the sa
34a30 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20  me interface on 
34a40 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
34a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
34a60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39 7d  ..**.** {F12979}
34a70 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
34a80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
34a90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
34aa0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a  ternal system.**
34ab0 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65 73            tables
34ac0 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f   such as sqlite_
34ad0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
34ae0 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d  e_sequence are m
34af0 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  odified..**.** {
34b00 46 31 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f  F12981} The seco
34b10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
34b20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62  the update callb
34b30 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ack .**         
34b40 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
34b50 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
34b60 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b  ITE_DELETE] or [
34b70 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a  SQLITE_UPDATE],.
34b80 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70 65  **          depe
34b90 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
34ba0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
34bb0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
34bc0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
34bd0 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68  *.** {F12983} Th
34be0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
34bf0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
34c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
34c10 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a  tain pointers.**
34c20 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72            to zer
34c30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
34c40 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63 68  -8 strings which
34c50 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f   are the names o
34c60 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
34c70 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74    database and t
34c80 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65 69  able that is bei
34c90 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20  ng updated...** 
34ca0 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e  {F12985} The fin
34cb0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
34cc0 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77  meter is the row
34cd0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66  id of the row af
34ce0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
34cf0 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72  the change occur
34d00 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
34d10 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34d20 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34d30 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
34d40 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
34d50 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
34d60 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
34d70 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
34d80 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
34d90 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
34da0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20  red Pager Cache 
34db0 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10330}.**.** T
34dc0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
34dd0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
34de0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
34df0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
34e00 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
34e10 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
34e20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69  between connecti
34e30 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ons to the same 
34e40 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61  database..** Sha
34e50 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
34e60 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
34e70 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61  is true and disa
34e80 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
34e90 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65  ment.** is false
34ea0 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68  ..**.** Cache sh
34eb0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
34ec0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a   and disabled.**
34ed0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
34ee0 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68  rocess. {END} Th
34ef0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
34f00 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
34f10 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e  ion 3.5.0..** In
34f20 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
34f30 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69  of SQLite, shari
34f40 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  ng was.** enable
34f50 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
34f60 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
34f70 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34f80 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
34f90 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
34fa0 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
34fb0 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
34fc0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
34fd0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34fe0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
34ff0 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
35000 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
35010 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
35020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
35030 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
35040 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
35050 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
35060 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
35070 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
35080 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  ..**.** Virtual 
35090 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65  tables cannot be
350a0 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61   used with a sha
350b0 72 65 64 20 63 61 63 68 65 2e 20 20 20 57 68 65  red cache.   Whe
350c0 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
350d0 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
350e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
350f0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
35100 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
35110 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
35120 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
35130 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
35140 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35150 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
35160 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
35170 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e   cache was.** en
35180 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
35190 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  d successfully. 
351a0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
351b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
351c0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
351d0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
351e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
351f0 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d  ault. But this m
35200 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a  ight change in.*
35210 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  * future release
35220 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70  s of SQLite.  Ap
35230 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
35240 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65  care about share
35250 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69  d.** cache setti
35260 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74  ng should set it
35270 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a   explicitly..**.
35280 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
35290 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20 41  * .** {F10331} A
352a0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
352b0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
352c0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
352d0 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20  _cache(B)].**   
352e0 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62         will enab
352f0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68  le or disable sh
35300 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20  ared cache mode 
35310 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 65  for any subseque
35320 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
35330 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
35340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
35350 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
35360 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  ss..**.** {F1033
35370 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 63  6} When shared c
35380 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
35390 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
353a0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a  eate_module()].*
353b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
353c0 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  face will always
353d0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
353e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d  ..**.** {F10337}
353f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
35400 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
35410 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(B)] interface 
35420 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
35430 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20      [SQLITE_OK] 
35440 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
35450 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
35460 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66  isabled successf
35470 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ully..**.** {F10
35480 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68  339} Shared cach
35490 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
354a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74   default..*/.int
354b0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
354c0 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
354d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
354e0 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20  EF:  Attempt To 
354f0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
35500 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F17340}.**.** 
35510 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
35520 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
35530 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
35540 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74  to.** free N byt
35550 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
35560 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
35570 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
35580 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
35590 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
355a0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
355b0 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72  ry. {END}  Memor
355c0 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63  y used.** to cac
355d0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
355e0 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
355f0 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
35600 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e  xample of.** non
35610 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
35620 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65 6c 65  y.  Sqlite3_rele
35630 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
35640 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
35650 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
35660 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
35670 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
35680 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  or less.** than 
35690 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
356a0 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  sted..**.** INVA
356b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
356c0 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  17341} The [sqli
356d0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
356e0 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ry(N)] interface
356f0 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20   attempts to.** 
35700 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e 20           free N 
35710 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
35720 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
35730 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
35740 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  al.**          m
35750 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
35760 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
35770 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a  tabase library..
35780 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54  **.** {F16342} T
35790 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  he [sqlite3_rele
357a0 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72  ase_memory(N)] r
357b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
357c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
357d0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
357e0 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67  freed, which mig
357f0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
35800 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
35810 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
35820 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74  equested..*/.int
35830 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
35840 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
35850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
35860 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
35870 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37  n Heap Size {F17
35880 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  350}.**.** The s
35890 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
358a0 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
358b0 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20 22  ce.** places a "
358c0 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74  soft" limit on t
358d0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
358e0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
358f0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  y be allocated.*
35900 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49 66 20  * by SQLite. If 
35910 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
35920 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
35930 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75  ted .** that wou
35940 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73 6f  ld exceed the so
35950 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
35960 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
35970 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20  memory()] is.** 
35980 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d  invoked one or m
35990 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
359a0 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
359b0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
359c0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65  ation.** is made
359d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69  ..**.** The limi
359e0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
359f0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a 2a  t", because if.*
35a00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
35a10 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
35a20 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
35a30 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
35a40 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
35a50 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
35a60 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
35a70 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
35a80 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
35a90 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
35aa0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
35ab0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
35ac0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
35ad0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
35ae0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
35af0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
35b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
35b10 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
35b20 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
35b30 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
35b40 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
35b50 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
35b60 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
35b70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
35b80 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
35b90 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
35ba0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
35bb0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
35bc0 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
35bd0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
35be0 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
35bf0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
35c00 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
35c10 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
35c20 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
35c30 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
35c40 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64  it is .** called
35c50 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
35c60 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
35c70 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
35c80 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
35c90 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
35ca0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
35cb0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
35cc0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
35cd0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
35ce0 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
35cf0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
35d00 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
35d10 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
35d20 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
35d30 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
35d40 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35d50 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
35d60 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
35d70 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
35d80 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
35d90 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
35da0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
35db0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
35dc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
35dd0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
35de0 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
35df0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
35e00 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
35e10 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
35e20 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
35e30 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
35e40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
35e50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d  :.**.** {F16351}
35e60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
35e70 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
35e80 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63  ] interface plac
35e90 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a  es a soft limit.
35ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e  **          of N
35eb0 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d   bytes on the am
35ec0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
35ed0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
35ee0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20  allocated.**    
35ef0 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c        using [sql
35f00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
35f10 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
35f20 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69  oc()] at any poi
35f30 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nt.**          i
35f40 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n time..**.** {F
35f50 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c  16352} If a call
35f60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
35f70 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
35f80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f  e3_realloc()] wo
35f90 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  uld.**          
35fa0 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20  cause the total 
35fb0 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61  amount of alloca
35fc0 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78  ted memory to ex
35fd0 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  ceed the.**     
35fe0 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c       soft heap l
35ff0 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69  imit, then [sqli
36000 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36010 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
36020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
36030 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  an attempt to re
36040 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  duce the memory 
36050 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70  usage prior to p
36060 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20  roceeding.**    
36070 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d        with the m
36080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
36090 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20   attempt..**.** 
360a0 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74  {F16353} Calls t
360b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
360c0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
360d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
360e0 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20   trigger.**     
360f0 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f       attempts to
36100 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
36110 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65  sage through the
36120 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63  .**          mec
36140 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20  hanism continue 
36150 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65  even if the atte
36160 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65  mpt to reduce me
36170 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
36180 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63   usage is unsucc
36190 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essful..**.** {F
361a0 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76  16354} A negativ
361b0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
361c0 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20  for N in a call 
361d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
361e0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
361f0 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e  p_limit(N)] mean
36200 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
36210 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20  no soft.**      
36220 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61      heap limit a
36230 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  nd [sqlite3_rele
36240 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
36250 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20  ll only be.**   
36260 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68         called wh
36270 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d  en memory is com
36280 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65  pletely exhauste
36290 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35  d..**.** {F16355
362a0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  } The default va
362b0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
362c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
362d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ero..**.** {F163
362e0 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  58} Each call to
362f0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
36300 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76  eap_limit(N)] ov
36310 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20  errides the.**  
36320 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73          values s
36330 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20  et by all prior 
36340 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  calls..*/.void s
36350 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
36360 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
36370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
36380 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
36390 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
363a0 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35  f A Table {F1285
363b0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
363c0 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73  utine.** returns
363d0 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74   meta-data about
363e0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
363f0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
36400 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
36410 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
36420 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
36430 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64  on handle passed
36440 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
36450 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d  nction .** argum
36460 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ent..**.** The c
36470 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
36480 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
36490 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
364a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
364b0 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  o .** this funct
364c0 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
364d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
364e0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
364f0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36500 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
36510 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
36520 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
36530 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
36540 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
36550 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
36560 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
36570 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
36580 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
36590 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
365a0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
365b0 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68   algorithm as th
365c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
365d0 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65  e uses to .** re
365e0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
365f0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
36600 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
36610 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
36620 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
36630 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
36640 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
36650 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  umn .** name of 
36660 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
36670 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
36680 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
36690 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a  se parameters .*
366a0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
366b0 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d  *.** Meta inform
366c0 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  ation is returne
366d0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
366e0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
366f0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a  ions passed as.*
36700 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75  * the 5th and su
36710 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
36720 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
36730 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65  tion. Any of the
36740 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73  se .** arguments
36750 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e   may be NULL, in
36760 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
36770 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
36780 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a  ement of meta .*
36790 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
367a0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
367b0 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
367c0 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
367d0 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
367e0 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
367f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
36800 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
36810 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
36820 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
36830 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
36840 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
36850 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
36860 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
36870 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
36880 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
36890 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
368a0 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
368b0 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
368c0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
368d0 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
368e0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
368f0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
36900 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
36910 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
36920 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
36930 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
36940 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
36950 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
36960 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
36970 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
36980 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
36990 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
369a0 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
369b0 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
369c0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
369d0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
369e0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
369f0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
36a00 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
36a10 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
36a20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36a30 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
36a40 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
36a50 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
36a60 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
36a70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
36a80 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
36a90 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
36aa0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
36ab0 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
36ac0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
36ad0 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
36ae0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
36af0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
36b00 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
36b10 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
36b20 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
36b30 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
36b40 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
36b50 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
36b60 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
36b70 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
36b80 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
36b90 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
36ba0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
36bb0 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
36bc0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
36bd0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
36be0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
36bf0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
36c00 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
36c10 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
36c20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
36c30 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
36c40 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
36c50 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
36c60 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
36c70 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
36c80 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
36c90 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
36ca0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
36cb0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
36cc0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
36cd0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
36ce0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
36cf0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
36d00 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
36d10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
36d20 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
36d30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
36d40 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
36d50 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
36d60 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
36d70 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
36d80 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
36d90 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
36da0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
36db0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
36dc0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
36dd0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
36de0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
36e00 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
36e10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e30 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
36e40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
36e50 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36e60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36e70 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
36e80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36e90 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
36ea0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
36eb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36ec0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
36ed0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
36ee0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
36ef0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
36f00 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
36f10 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
36f20 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
36f30 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
36f40 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
36f50 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
36f60 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
36f70 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
36f80 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
36f90 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
36fa0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
36fb0 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
36fc0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
36fd0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
36fe0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
36ff0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
37000 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
37010 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
37020 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
37030 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
37040 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
37050 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
37060 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
37070 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
37080 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
37090 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
370a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
370b0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
370c0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
370d0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
370e0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
370f0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
37100 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
37110 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
37120 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
37130 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
37140 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
37150 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
37160 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
37170 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
37180 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
37190 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
371a0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
371b0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
371c0 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
371d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
371e0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
371f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
37200 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
37210 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
37220 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
37230 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
37240 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
37250 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
37260 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
37270 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
37280 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
37290 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
372a0 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
372b0 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
372c0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
372d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
372e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
372f0 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
37300 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
37310 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
37320 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
37330 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37340 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
37350 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
37360 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
37370 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
37380 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
37390 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
373a0 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
373b0 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
373c0 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
373d0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
373e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
373f0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
37400 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
37410 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
37420 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
37430 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
37440 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
37450 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
37460 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
37470 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
37480 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
37490 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
374a0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
374b0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
374c0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
374d0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
374e0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
374f0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
37500 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
37510 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
37520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
37530 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
37540 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
37550 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
37560 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
37570 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
37580 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
37590 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
375a0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
375b0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
375c0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
375d0 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
375e0 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
375f0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
37600 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
37610 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
37620 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
37630 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
37640 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
37650 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
37660 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
37670 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
37680 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
37690 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
376a0 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
376b0 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
376c0 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
376d0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
376e0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
376f0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
37700 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
37710 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
37720 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
37730 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
37740 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
37750 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
37760 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
37770 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
37780 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
37790 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
377a0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
377b0 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
377c0 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
377d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
377e0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
377f0 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
37800 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
37810 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
37820 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
37830 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
37840 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
37850 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65  invoked.** whene
37860 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  ver a new databa
37870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37880 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
37890 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
378a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
378b0 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
378c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b  e3_open_v2()]. {
378d0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
378e0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
378f0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
37900 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
37910 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
37920 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
37930 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
37940 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
37950 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
37960 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
37970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
37980 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d  ..**.** {F12642}
37990 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
379a0 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
379b0 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
379c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
379d0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
379e0 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
379f0 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
37a00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d  ..**.** {F12643}
37a10 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
37a20 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
37a30 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
37a40 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
37a50 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
37a60 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c  from sqlite_mall
37a70 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79  oc(). {END} If y
37a80 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20  ou run a memory 
37a90 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20  leak.** checker 
37aa0 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20  on your program 
37ab0 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61  and it reports a
37ac0 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66   leak because of
37ad0 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20   this.** array, 
37ae0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  then invoke [sql
37af0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
37b00 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
37b10 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
37b20 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
37b30 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mory..**.** {F12
37b40 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
37b50 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
37b60 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
37b70 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
37b80 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
37b90 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
37ba0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
37bb0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
37bc0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
37bd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
37be0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37bf0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
37c00 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
37c10 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
37c20 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
37c30 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
37c40 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36  n Loading {F1266
37c50 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31  0}.**.** {F12661
37c60 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
37c70 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
37c80 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
37c90 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  ed.** automatic 
37ca0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
37cb0 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  }  This.** routi
37cc0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
37cd0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
37ce0 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  r [sqlite3_auto_
37cf0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
37d00 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
37d10 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20  2662} This call 
37d20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74  disabled automat
37d30 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
37d40 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
37d50 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ND}.**.** This i
37d60 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
37d70 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
37d80 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
37d90 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
37da0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
37db0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
37dc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37dd0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
37de0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
37df0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
37e00 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
37e10 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
37e20 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
37e30 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
37e40 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
37e50 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
37e60 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
37e70 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
37e80 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
37e90 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
37ea0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
37eb0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
37ec0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
37ed0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
37ee0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
37ef0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
37f00 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
37f10 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
37f20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
37f30 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
37f40 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
37f50 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
37f60 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
37f70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
37f80 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
37f90 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
37fa0 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
37fb0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
37fc0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
37fd0 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
37fe0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
37ff0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
38000 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
38010 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
38020 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
38030 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
38040 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
38050 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
38060 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
38070 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
38080 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
38090 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
380a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
380b0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
380c0 62 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a  bject {F18000}.*
380d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
380e0 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a  te3_module.**.**
380f0 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63   A module is a c
38100 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20  lass of virtual 
38110 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f  tables.  Each mo
38120 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a  dule is defined.
38130 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63  ** by an instanc
38140 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
38150 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  ng structure.  T
38160 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f  his structure co
38170 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79  nsists.** mostly
38180 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20   of methods for 
38190 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73  the module..*/.s
381a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
381b0 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65  dule {.  int iVe
381c0 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
381d0 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a  Create)(sqlite3*
381e0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
381f0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
38200 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
38210 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
38220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
38230 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
38240 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
38250 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28  int (*xConnect)(
38260 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
38270 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
38280 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
38290 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
382a0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
382b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
382c0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
382d0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  r**);.  int (*xB
382e0 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65  estIndex)(sqlite
382f0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
38300 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
38310 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69  o*);.  int (*xDi
38320 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  sconnect)(sqlite
38330 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
38340 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79    int (*xDestroy
38350 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
38360 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
38370 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
38380 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
38390 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
383a0 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69  **ppCursor);.  i
383b0 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
383c0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
383d0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
383e0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ter)(sqlite3_vta
383f0 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69  b_cursor*, int i
38400 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61  dxNum, const cha
38410 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20  r *idxStr,.     
38420 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
38430 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  rgc, sqlite3_val
38440 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e  ue **argv);.  in
38450 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74  t (*xNext)(sqlit
38460 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
38470 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28  ;.  int (*xEof)(
38480 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
38490 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
384a0 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f  Column)(sqlite3_
384b0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
384c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
384d0 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
384e0 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74  owid)(sqlite3_vt
384f0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
38500 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  te3_int64 *pRowi
38510 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  d);.  int (*xUpd
38520 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ate)(sqlite3_vta
38530 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  b *, int, sqlite
38540 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69  3_value **, sqli
38550 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20  te3_int64 *);.  
38560 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71  int (*xBegin)(sq
38570 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
38580 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  b);.  int (*xSyn
38590 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  c)(sqlite3_vtab 
385a0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
385b0 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65  *xCommit)(sqlite
385c0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
385d0 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63    int (*xRollbac
385e0 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  k)(sqlite3_vtab 
385f0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
38600 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28  *xFindFunction)(
38610 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
38620 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63  tab, int nArg, c
38630 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
38640 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
38650 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a           void (*
38660 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  *pxFunc)(sqlite3
38670 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
38680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
38690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
386a0 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70         void **pp
386b0 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78  Arg);..  int (*x
386c0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
386d0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
386e0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
386f0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
38700 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
38710 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
38720 6d 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a  mation {F18100}.
38730 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
38740 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
38750 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38760 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
38770 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
38780 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
38790 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
387a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
387b0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
387c0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
387d0 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65  xBestIndex.** me
387e0 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74  thod of an sqlit
387f0 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  e3_module.  The 
38800 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
38810 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
38820 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
38830 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
38840 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
38850 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
38860 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
38870 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
38880 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
38890 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
388a0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
388b0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
388c0 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
388d0 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  .** form:.**.** 
388e0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f          column O
388f0 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65  P expr.**.** Whe
38900 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
38910 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
38920 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68  r &gt;=.  .** Th
38930 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
38940 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a  rator is stored.
38950 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ** in aConstrain
38960 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
38970 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
38980 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a   is stored in .*
38990 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
389a0 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
389b0 72 61 69 6e